diff --git a/CHANGELOG.md b/CHANGELOG.md index 8f39b26da9..2c8c561bcf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [0.83.1](https://github.com/kurtosis-tech/kurtosis/compare/0.83.0...0.83.1) (2023-09-18) + + +### Features + +* changes to the package manager config and the files artifact view ([#1322](https://github.com/kurtosis-tech/kurtosis/issues/1322)) ([e2b0d2b](https://github.com/kurtosis-tech/kurtosis/commit/e2b0d2b50ffa7edd2ff50eeba4c0887aa38ff27b)) + ## [0.83.0](https://github.com/kurtosis-tech/kurtosis/compare/0.82.24...0.83.0) (2023-09-18) diff --git a/LICENSE.md b/LICENSE.md index bae4b0c7b4..d099707e7b 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.83.0 +Licensed Work: Kurtosis 0.83.1 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 889df426ca..30a800d556 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.83.0" + KurtosisVersion = "0.83.1" // !!!!!!!!!!! DO NOT UPDATE! WILL BE MANUALLY UPDATED DURING THE RELEASE PROCESS !!!!!!!!!!!!!!!!!!!!!! ) diff --git a/api/rust/Cargo.toml b/api/rust/Cargo.toml index b8777c1450..0066ba4833 100644 --- a/api/rust/Cargo.toml +++ b/api/rust/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "kurtosis-sdk" -version = "0.83.0" +version = "0.83.1" license = "BUSL-1.1" description = "Rust SDK for Kurtosis" edition = "2021" diff --git a/api/typescript/package.json b/api/typescript/package.json index 309ca9661a..f7e29c9fe1 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.83.0", + "version": "0.83.1", "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 65fbea280d..ed1985ff0c 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.83.0" +export const KURTOSIS_VERSION: string = "0.83.1" // !!!!!!!!!!! DO NOT UPDATE! WILL BE MANUALLY UPDATED DURING THE RELEASE PROCESS !!!!!!!!!!!!!!!!!!!!!! diff --git a/docs/versioned_docs/version-0.83.1/best-practices.md b/docs/versioned_docs/version-0.83.1/best-practices.md new file mode 100644 index 0000000000..f4d4190c92 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/best-practices.md @@ -0,0 +1,57 @@ +--- +title: Best Practices +sidebar_label: Best Practices +slug: /best-practices +--- + +Passing package arguments to the CLI +------------------------------- +Passing [package parameters][package-parameterization] via 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-params.json)" + ``` + The double quotes around the `$(cat my-params.json)` are important so any spaces inside `my-params.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` + +Choosing service names in Kurtosis +---------------------------------- +Kurtosis service names implements [RFC-1035](https://datatracker.ietf.org/doc/html/rfc1035), meaning the names of all services must be a valid [RFC-1035 Label Name](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#rfc-1035-label-names). Tactically this means a service name must: + +- contain at most 63 characters +- contain only lowercase alphanumeric characters or '-' +- start with an alphabetic character +- end with an alphanumeric character + +Failure to adhere to the above standards will result in errors when running Kurtosis. + + + + +[package-parameterization]: ./concepts-reference/packages.md#parameterization + +[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.83.1/changelog.md b/docs/versioned_docs/version-0.83.1/changelog.md new file mode 100644 index 0000000000..2c8c561bcf --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/changelog.md @@ -0,0 +1,1518 @@ +# Changelog + +## [0.83.1](https://github.com/kurtosis-tech/kurtosis/compare/0.83.0...0.83.1) (2023-09-18) + + +### Features + +* changes to the package manager config and the files artifact view ([#1322](https://github.com/kurtosis-tech/kurtosis/issues/1322)) ([e2b0d2b](https://github.com/kurtosis-tech/kurtosis/commit/e2b0d2b50ffa7edd2ff50eeba4c0887aa38ff27b)) + +## [0.83.0](https://github.com/kurtosis-tech/kurtosis/compare/0.82.24...0.83.0) (2023-09-18) + + +### ⚠ BREAKING CHANGES + +* rename assert to verify ([#1295](https://github.com/kurtosis-tech/kurtosis/issues/1295)) +* print a downloaded container images summary after pulling images from remote or locally ([#1315](https://github.com/kurtosis-tech/kurtosis/issues/1315)) + +### Features + +* Clean CLI command now removes unsued Kurtosis images ([#1314](https://github.com/kurtosis-tech/kurtosis/issues/1314)) ([a924f4a](https://github.com/kurtosis-tech/kurtosis/commit/a924f4a7a1b707695bd8ffc7208c1871ea0432ad)), closes [#1131](https://github.com/kurtosis-tech/kurtosis/issues/1131) +* print a downloaded container images summary after pulling images from remote or locally ([#1315](https://github.com/kurtosis-tech/kurtosis/issues/1315)) ([b822870](https://github.com/kurtosis-tech/kurtosis/commit/b822870d10bcb3614ec3cf2fed3db46dd52d9d42)), closes [#1292](https://github.com/kurtosis-tech/kurtosis/issues/1292) + + +### Code Refactoring + +* rename assert to verify ([#1295](https://github.com/kurtosis-tech/kurtosis/issues/1295)) ([651df40](https://github.com/kurtosis-tech/kurtosis/commit/651df406ecf66518005c806d9ccd1bd3260e4af3)) + +## [0.82.24](https://github.com/kurtosis-tech/kurtosis/compare/0.82.23...0.82.24) (2023-09-14) + + +### Bug Fixes + +* propagate failed img pull error to response line ([#1302](https://github.com/kurtosis-tech/kurtosis/issues/1302)) ([9a4a928](https://github.com/kurtosis-tech/kurtosis/commit/9a4a9284c4dff87dfd861d2bd8878748abe5c3b8)) +* revert always pull latest img ([#1306](https://github.com/kurtosis-tech/kurtosis/issues/1306)) ([d4ef19e](https://github.com/kurtosis-tech/kurtosis/commit/d4ef19e1297ae9373263b1392a1a7fead1892af7)) + +## [0.82.23](https://github.com/kurtosis-tech/kurtosis/compare/0.82.22...0.82.23) (2023-09-14) + + +### Features + +* folks can delete enclaves from the frontend ([#1250](https://github.com/kurtosis-tech/kurtosis/issues/1250)) ([ee11b7c](https://github.com/kurtosis-tech/kurtosis/commit/ee11b7c2a79f153d7d8aa023ee7c03d54065a0c1)) +* The current enclave plan is now persisted to the enclave DB every times the execution finishes ([#1280](https://github.com/kurtosis-tech/kurtosis/issues/1280)) ([33d867e](https://github.com/kurtosis-tech/kurtosis/commit/33d867ed62cbf7621aecb775c8f1ba1c01c5d700)) + + +### Bug Fixes + +* follow logs ([#1298](https://github.com/kurtosis-tech/kurtosis/issues/1298)) ([9b0bcb7](https://github.com/kurtosis-tech/kurtosis/commit/9b0bcb779bd7c2dd12a359c868f16cf34ec69f13)) +* Reset the module global cache on every new interpretation to avoid using outdated modules ([#1291](https://github.com/kurtosis-tech/kurtosis/issues/1291)) ([81c5462](https://github.com/kurtosis-tech/kurtosis/commit/81c54623deb03cdcfb70b075b4a4367e8f4b4e36)) +* return after stream err ([#1301](https://github.com/kurtosis-tech/kurtosis/issues/1301)) ([f40559b](https://github.com/kurtosis-tech/kurtosis/commit/f40559b63ca99163336d0ce706d835a8e345e835)) + +## [0.82.22](https://github.com/kurtosis-tech/kurtosis/compare/0.82.21...0.82.22) (2023-09-11) + + +### Features + +* always pull latest image ([#1267](https://github.com/kurtosis-tech/kurtosis/issues/1267)) ([6706809](https://github.com/kurtosis-tech/kurtosis/commit/670680980957f5eaa5b0ec01ed0ee9b8973d58e7)) +* CLI run command option to disable user services port forwarding ([#1252](https://github.com/kurtosis-tech/kurtosis/issues/1252)) ([1c94378](https://github.com/kurtosis-tech/kurtosis/commit/1c94378b9342bbe07647d8c61c47197f5aafcc18)), closes [#1236](https://github.com/kurtosis-tech/kurtosis/issues/1236) +* retain logs for x weeks ([#1235](https://github.com/kurtosis-tech/kurtosis/issues/1235)) ([5f50c8c](https://github.com/kurtosis-tech/kurtosis/commit/5f50c8cc8bf9e5d99570c1c618a5ec367ed194a2)) + + +### Bug Fixes + +* inline upgrade warning ([#1254](https://github.com/kurtosis-tech/kurtosis/issues/1254)) ([33ef03a](https://github.com/kurtosis-tech/kurtosis/commit/33ef03a5c3553778d60597cc177893a0c50d6076)), closes [#1244](https://github.com/kurtosis-tech/kurtosis/issues/1244) + +## [0.82.21](https://github.com/kurtosis-tech/kurtosis/compare/0.82.20...0.82.21) (2023-09-06) + + +### Bug Fixes + +* the runtime value store now supports `starlark.Bool` value types ([#1249](https://github.com/kurtosis-tech/kurtosis/issues/1249)) ([825f7cd](https://github.com/kurtosis-tech/kurtosis/commit/825f7cdb7b77bfb3a88d658b839141f965ca4fb6)) + +## [0.82.20](https://github.com/kurtosis-tech/kurtosis/compare/0.82.19...0.82.20) (2023-09-06) + + +### Bug Fixes + +* handle default string value properly ([#1243](https://github.com/kurtosis-tech/kurtosis/issues/1243)) ([6e49059](https://github.com/kurtosis-tech/kurtosis/commit/6e4905973715db54814cf678832a576a89b5fd28)) +* Runtime values created by `add_services` were incorrect in the case of a skipped instruction ([#1239](https://github.com/kurtosis-tech/kurtosis/issues/1239)) ([3412486](https://github.com/kurtosis-tech/kurtosis/commit/341248627daa1be920985137080b8705662f1993)) + +## [0.82.19](https://github.com/kurtosis-tech/kurtosis/compare/0.82.18...0.82.19) (2023-09-05) + + +### Features + +* Add starlark.Value serializer/deserializer for enclave persistence ([#1229](https://github.com/kurtosis-tech/kurtosis/issues/1229)) ([45b9330](https://github.com/kurtosis-tech/kurtosis/commit/45b9330892a6559d75e8859ef6b9b3dff1f09b1b)) + + +### Bug Fixes + +* close engine server which is important for triggering the idle enclaves remotion process ([#1219](https://github.com/kurtosis-tech/kurtosis/issues/1219)) ([912e855](https://github.com/kurtosis-tech/kurtosis/commit/912e8551069da797cdbf86e21046f4444ed42b80)) +* disabled time.now() ([#1231](https://github.com/kurtosis-tech/kurtosis/issues/1231)) ([26e8d40](https://github.com/kurtosis-tech/kurtosis/commit/26e8d40dc08a9e534af814138eec598f9b21b1ac)) +* Does not delete runtime value during idepotent runs ([#1232](https://github.com/kurtosis-tech/kurtosis/issues/1232)) ([a06c247](https://github.com/kurtosis-tech/kurtosis/commit/a06c2473f9f13a3047d09dc74338d27de6ac24f0)) +* fix a sneaky segmentation fault where we were propagating a nil error ([#1222](https://github.com/kurtosis-tech/kurtosis/issues/1222)) ([666f4ee](https://github.com/kurtosis-tech/kurtosis/commit/666f4ee677f76f7828c065046c64394322085d74)) +* fix a typo in recipe result repository ([#1224](https://github.com/kurtosis-tech/kurtosis/issues/1224)) ([94a4b8b](https://github.com/kurtosis-tech/kurtosis/commit/94a4b8bc5fc79b69845ab4493eb70307cf9d7b0f)) + +## [0.82.18](https://github.com/kurtosis-tech/kurtosis/compare/0.82.17...0.82.18) (2023-09-01) + + +### Bug Fixes + +* markdown bug ([#1220](https://github.com/kurtosis-tech/kurtosis/issues/1220)) ([2ce4823](https://github.com/kurtosis-tech/kurtosis/commit/2ce4823718033d0c1c61ab1567107b79de039245)) + +## [0.82.17](https://github.com/kurtosis-tech/kurtosis/compare/0.82.16...0.82.17) (2023-09-01) + + +### Features + +* enable retrieving logs from services in stopped enclaves ([#1213](https://github.com/kurtosis-tech/kurtosis/issues/1213)) ([83c269c](https://github.com/kurtosis-tech/kurtosis/commit/83c269c4a24e377f5446dcda68f0fa4acd4ef7ff)) +* Pass enclave name to Starlark global `kurtosis` module ([#1216](https://github.com/kurtosis-tech/kurtosis/issues/1216)) ([c5f2c97](https://github.com/kurtosis-tech/kurtosis/commit/c5f2c97bb349e114e4e7235ce839b1fb9aa00161)) +* Persist runtime value store ([#1170](https://github.com/kurtosis-tech/kurtosis/issues/1170)) ([cfec9b3](https://github.com/kurtosis-tech/kurtosis/commit/cfec9b3028d9349cf2b102cb1818cf5e2a41f047)) +* track the analytics toggle event ([#1217](https://github.com/kurtosis-tech/kurtosis/issues/1217)) ([10c461f](https://github.com/kurtosis-tech/kurtosis/commit/10c461f7b546cc260540725a64e624d9f99b04f1)) + +## [0.82.16](https://github.com/kurtosis-tech/kurtosis/compare/0.82.15...0.82.16) (2023-08-31) + + +### Features + +* added description ([#1214](https://github.com/kurtosis-tech/kurtosis/issues/1214)) ([4a95802](https://github.com/kurtosis-tech/kurtosis/commit/4a95802a86c251d01846cc8350f0cf69ca20a412)) + + +### Bug Fixes + +* add create enclave name and production mode for enclaves ([#1211](https://github.com/kurtosis-tech/kurtosis/issues/1211)) ([2760f48](https://github.com/kurtosis-tech/kurtosis/commit/2760f486da3941953ef2bfa81bea3115d5a1caa7)) +* made forwarding efficient by reducing calls to Kubernetes ([#1200](https://github.com/kurtosis-tech/kurtosis/issues/1200)) ([4df6a1c](https://github.com/kurtosis-tech/kurtosis/commit/4df6a1c2cb12e0dd9e55dbc51d3c6c2d68917ffd)) +* Remove 'kurtosis version' depending on the engine ([#1207](https://github.com/kurtosis-tech/kurtosis/issues/1207)) ([ab7dc02](https://github.com/kurtosis-tech/kurtosis/commit/ab7dc027df3949f1479502c2697cc351e3341021)), closes [#1206](https://github.com/kurtosis-tech/kurtosis/issues/1206) + +## [0.82.15](https://github.com/kurtosis-tech/kurtosis/compare/0.82.14...0.82.15) (2023-08-30) + + +### Bug Fixes + +* cluster set doesnt get into a weird state of no cluster being set ([#1055](https://github.com/kurtosis-tech/kurtosis/issues/1055)) ([c647035](https://github.com/kurtosis-tech/kurtosis/commit/c6470356e2939d4834d773a085e4b98c1cd44e7f)) +* enclave name validation to support valid DNS-1035 label rules ([#1204](https://github.com/kurtosis-tech/kurtosis/issues/1204)) ([74845a8](https://github.com/kurtosis-tech/kurtosis/commit/74845a85e627acc5ffc54162973457869fcc0887)) +* make test enclave creation support DNS label rules ([#1202](https://github.com/kurtosis-tech/kurtosis/issues/1202)) ([df61ecc](https://github.com/kurtosis-tech/kurtosis/commit/df61ecc783ade430a434fd129a42c54d1d742263)) +* Point to the engine restart command as part of the context switch failure remediation to not conflict with lower level commands ([#1191](https://github.com/kurtosis-tech/kurtosis/issues/1191)) ([f83e513](https://github.com/kurtosis-tech/kurtosis/commit/f83e513a1f2b0e136d4f61e92d4189125f900fd4)) +* removed the flaky tests ([#1205](https://github.com/kurtosis-tech/kurtosis/issues/1205)) ([b990674](https://github.com/kurtosis-tech/kurtosis/commit/b990674e20696023c22d1e37fa119bce480ce556)) +* this pr fixes the search issue. ([#1201](https://github.com/kurtosis-tech/kurtosis/issues/1201)) ([2a17b1b](https://github.com/kurtosis-tech/kurtosis/commit/2a17b1badd413bee892ff89d2c7697a2c1b32213)) + +## [0.82.14](https://github.com/kurtosis-tech/kurtosis/compare/0.82.13...0.82.14) (2023-08-29) + + +### Features + +* add creation dialog 2 ([#1194](https://github.com/kurtosis-tech/kurtosis/issues/1194)) ([b586a8a](https://github.com/kurtosis-tech/kurtosis/commit/b586a8a0aa5f84b2f6d5f8bff3079135d4ffde2e)) + +## [0.82.13](https://github.com/kurtosis-tech/kurtosis/compare/0.82.12...0.82.13) (2023-08-29) + + +### Bug Fixes + +* hyperlane package error ([#1193](https://github.com/kurtosis-tech/kurtosis/issues/1193)) ([e5946ad](https://github.com/kurtosis-tech/kurtosis/commit/e5946ad50fb3275cd7b26025c4901629427fbc4d)) + +## [0.82.12](https://github.com/kurtosis-tech/kurtosis/compare/0.82.11...0.82.12) (2023-08-29) + + +### Bug Fixes + +* `react-scripts` dependency changed on the engine frontend to fix a vulnerability reported by Dependabot ([#1179](https://github.com/kurtosis-tech/kurtosis/issues/1179)) ([e5e15f6](https://github.com/kurtosis-tech/kurtosis/commit/e5e15f6fd90455380d585c7e2cc7ebf434e1ea88)) +* handle package catalog edge case ([#1187](https://github.com/kurtosis-tech/kurtosis/issues/1187)) ([2a8a4c8](https://github.com/kurtosis-tech/kurtosis/commit/2a8a4c8a9f902ec3444d4ed1964427b81fc13409)) +* ui displays error logs ([#1185](https://github.com/kurtosis-tech/kurtosis/issues/1185)) ([6a2522b](https://github.com/kurtosis-tech/kurtosis/commit/6a2522ba96f9a2ab45dc944f5a1b9bc921d1904d)) +* user service streaming logs when the last line is not a completed JSON line ([#1175](https://github.com/kurtosis-tech/kurtosis/issues/1175)) ([fece446](https://github.com/kurtosis-tech/kurtosis/commit/fece446d97f11219595772ffd0b42917676b74e1)) + +## [0.82.11](https://github.com/kurtosis-tech/kurtosis/compare/0.82.10...0.82.11) (2023-08-29) + + +### Bug Fixes + +* it fixes the log font colour; it shows black now on the cloud em ([#1182](https://github.com/kurtosis-tech/kurtosis/issues/1182)) ([f13de9f](https://github.com/kurtosis-tech/kurtosis/commit/f13de9f61f1125bccf25535d9e90e7a62ea8375c)) + +## [0.82.10](https://github.com/kurtosis-tech/kurtosis/compare/0.82.9...0.82.10) (2023-08-28) + + +### Features + +* Production mode enclave ([#1171](https://github.com/kurtosis-tech/kurtosis/issues/1171)) ([84e8c71](https://github.com/kurtosis-tech/kurtosis/commit/84e8c7110731c0237c1a9ec5eb7cacfa22b7337b)) + +## [0.82.9](https://github.com/kurtosis-tech/kurtosis/compare/0.82.8...0.82.9) (2023-08-28) + + +### Features + +* added package to loader UI ([#1147](https://github.com/kurtosis-tech/kurtosis/issues/1147)) ([9a2edff](https://github.com/kurtosis-tech/kurtosis/commit/9a2edffd095bfa6b0dc760e974aae3ed7939e0c7)) + +## [0.82.8](https://github.com/kurtosis-tech/kurtosis/compare/0.82.7...0.82.8) (2023-08-28) + + +### Bug Fixes + +* Fix NPE in stacktrace ([#1172](https://github.com/kurtosis-tech/kurtosis/issues/1172)) ([32770ca](https://github.com/kurtosis-tech/kurtosis/commit/32770ca96513d5d4191f6e2f373cadc89120adc9)) +* fix the Discord link used by the `dicord` CLI command ([#1177](https://github.com/kurtosis-tech/kurtosis/issues/1177)) ([39d159a](https://github.com/kurtosis-tech/kurtosis/commit/39d159a5141d18a31ddc97d775bccbdd99c2a7ad)), closes [#1174](https://github.com/kurtosis-tech/kurtosis/issues/1174) + +## [0.82.7](https://github.com/kurtosis-tech/kurtosis/compare/0.82.6...0.82.7) (2023-08-28) + + +### Features + +* add header to instruct clients not to cache ([#1166](https://github.com/kurtosis-tech/kurtosis/issues/1166)) ([ad27761](https://github.com/kurtosis-tech/kurtosis/commit/ad27761f07306a851526b9424458fe5a54b6cd72)) +* Authorize enclave manager requests if the host matches the user's instance host ([#1163](https://github.com/kurtosis-tech/kurtosis/issues/1163)) ([093af33](https://github.com/kurtosis-tech/kurtosis/commit/093af33b4bc9ecf75814ee7c1a2b838379d961fb)) + +## [0.82.6](https://github.com/kurtosis-tech/kurtosis/compare/0.82.5...0.82.6) (2023-08-26) + + +### Bug Fixes + +* paths ([#1162](https://github.com/kurtosis-tech/kurtosis/issues/1162)) ([e1a9fb0](https://github.com/kurtosis-tech/kurtosis/commit/e1a9fb013acfb8fdc0f638094ab5c596ada0330c)) + +## [0.82.5](https://github.com/kurtosis-tech/kurtosis/compare/0.82.4...0.82.5) (2023-08-24) + + +### Bug Fixes + +* get service logs tail ([#1156](https://github.com/kurtosis-tech/kurtosis/issues/1156)) ([734b1a8](https://github.com/kurtosis-tech/kurtosis/commit/734b1a8d7431a6e2c35f7abedef803facdffb56d)) + +## [0.82.4](https://github.com/kurtosis-tech/kurtosis/compare/0.82.3...0.82.4) (2023-08-24) + + +### Features + +* use proxy url ([#1158](https://github.com/kurtosis-tech/kurtosis/issues/1158)) ([7c44373](https://github.com/kurtosis-tech/kurtosis/commit/7c44373fc18ce23117fa7c70155c53a94be09e59)) + + +### Bug Fixes + +* Create portal client daemon client only on remote context. ([#1155](https://github.com/kurtosis-tech/kurtosis/issues/1155)) ([b7ae803](https://github.com/kurtosis-tech/kurtosis/commit/b7ae803f24c47046171188b5bba308f5cb0d51f3)) + +## [0.82.3](https://github.com/kurtosis-tech/kurtosis/compare/0.82.2...0.82.3) (2023-08-24) + + +### Features + +* enable dynamic api host for Enclave Manager and auth enforcement ([#1153](https://github.com/kurtosis-tech/kurtosis/issues/1153)) ([a39706e](https://github.com/kurtosis-tech/kurtosis/commit/a39706e7ab2a7af46afd590b0c9fccf6cd65f4c4)) + +## [0.82.2](https://github.com/kurtosis-tech/kurtosis/compare/0.82.1...0.82.2) (2023-08-24) + + +### Features + +* make paths relative to support embedding in other contexts ([#1151](https://github.com/kurtosis-tech/kurtosis/issues/1151)) ([74fbe53](https://github.com/kurtosis-tech/kurtosis/commit/74fbe53c07e1dd0c2ae994e2246d1b7033b1bad3)) + + +### Bug Fixes + +* lower calls to backend by doing get all services more efficiently ([#1143](https://github.com/kurtosis-tech/kurtosis/issues/1143)) ([a2c0dcc](https://github.com/kurtosis-tech/kurtosis/commit/a2c0dcc0bc3874338ac6fbd5c42bf45163a628dc)), closes [#1074](https://github.com/kurtosis-tech/kurtosis/issues/1074) + +## [0.82.1](https://github.com/kurtosis-tech/kurtosis/compare/0.82.0...0.82.1) (2023-08-23) + + +### Features + +* add enclave manager ([#1148](https://github.com/kurtosis-tech/kurtosis/issues/1148)) ([54d94c5](https://github.com/kurtosis-tech/kurtosis/commit/54d94c5e80a2a89d5dbf0e9759871007b9141005)) +* Running Kurtosis in Kurtosis cloud doc ([#1142](https://github.com/kurtosis-tech/kurtosis/issues/1142)) ([dbff171](https://github.com/kurtosis-tech/kurtosis/commit/dbff17164c4f37070db2121fcffd04f1866c45a3)) + + +### Bug Fixes + +* use connectrpc instead of bufbuild ([#1144](https://github.com/kurtosis-tech/kurtosis/issues/1144)) ([d98bed1](https://github.com/kurtosis-tech/kurtosis/commit/d98bed1b9854624a97c9b2c452071ee476cf282d)) + +## [0.82.0](https://github.com/kurtosis-tech/kurtosis/compare/0.81.9...0.82.0) (2023-08-22) + + +### ⚠ BREAKING CHANGES + +* Portal remote endpoints and forward port wait until ready option ([#1124](https://github.com/kurtosis-tech/kurtosis/issues/1124)) + +### Features + +* Add possibility to pass env vars to enclave ([#1134](https://github.com/kurtosis-tech/kurtosis/issues/1134)) ([9889e6f](https://github.com/kurtosis-tech/kurtosis/commit/9889e6f126666451d378965e764a80d79ba72443)) +* added connect-go for engine ([#879](https://github.com/kurtosis-tech/kurtosis/issues/879)) ([8c0121c](https://github.com/kurtosis-tech/kurtosis/commit/8c0121cac01f53d858bbec90d87bec20f122430d)) +* make kurtosis service logs pull from persistent volume ([#1121](https://github.com/kurtosis-tech/kurtosis/issues/1121)) ([8e52a24](https://github.com/kurtosis-tech/kurtosis/commit/8e52a2489cb67707373f802c00dd4f37e7b56931)) +* Portal remote endpoints and forward port wait until ready option ([#1124](https://github.com/kurtosis-tech/kurtosis/issues/1124)) ([f4e3e77](https://github.com/kurtosis-tech/kurtosis/commit/f4e3e773463b98f7376ee49b70ab28d9da60caae)) +* propogated bridge network ip address ([#1135](https://github.com/kurtosis-tech/kurtosis/issues/1135)) ([04ed723](https://github.com/kurtosis-tech/kurtosis/commit/04ed723c00ac9adb820c56f1db6998eff483f294)) + + +### Bug Fixes + +* More flexible context config unmarshaller ([#1132](https://github.com/kurtosis-tech/kurtosis/issues/1132)) ([7892bda](https://github.com/kurtosis-tech/kurtosis/commit/7892bda4fe0a8e0251b9036e9b7cc18843eefcc1)) +* Use portal deps from the main branch - Part 2 ([#1138](https://github.com/kurtosis-tech/kurtosis/issues/1138)) ([f0a2353](https://github.com/kurtosis-tech/kurtosis/commit/f0a2353b68a5580552f66fb468a9bd3681b3e7d6)) +* Use portal deps from the main branch ([#1136](https://github.com/kurtosis-tech/kurtosis/issues/1136)) ([b9da525](https://github.com/kurtosis-tech/kurtosis/commit/b9da5254edbb291a6a1354c67bcbc357bde71c6c)) + +## [0.81.9](https://github.com/kurtosis-tech/kurtosis/compare/0.81.8...0.81.9) (2023-08-17) + + +### Features + +* Implements service registration repository in Docker Kurtosis Backend ([#1105](https://github.com/kurtosis-tech/kurtosis/issues/1105)) ([723a14e](https://github.com/kurtosis-tech/kurtosis/commit/723a14e041a74744337aeb38d64fa86306b36883)) + +## [0.81.8](https://github.com/kurtosis-tech/kurtosis/compare/0.81.7...0.81.8) (2023-08-15) + + +### Bug Fixes + +* make enclave identifier arg passable to service identifier completion provider ([#1107](https://github.com/kurtosis-tech/kurtosis/issues/1107)) ([051bc95](https://github.com/kurtosis-tech/kurtosis/commit/051bc95287fc56ed1af077c8992edeef935bdc57)), closes [#1094](https://github.com/kurtosis-tech/kurtosis/issues/1094) + +## [0.81.7](https://github.com/kurtosis-tech/kurtosis/compare/0.81.6...0.81.7) (2023-08-14) + + +### Features + +* add connect-go bindings generation to cloud ([#1090](https://github.com/kurtosis-tech/kurtosis/issues/1090)) ([8ba54d0](https://github.com/kurtosis-tech/kurtosis/commit/8ba54d099e550669d6c3be185880bc1f73ac24f3)) + + +### Bug Fixes + +* move where logs aggregator is destroyed ([#1110](https://github.com/kurtosis-tech/kurtosis/issues/1110)) ([aa392f3](https://github.com/kurtosis-tech/kurtosis/commit/aa392f39557afb976a6b74db5c80ffea991b4294)) + +## [0.81.6](https://github.com/kurtosis-tech/kurtosis/compare/0.81.5...0.81.6) (2023-08-11) + + +### Features + +* add more endpoints to support the Cloud ([#1077](https://github.com/kurtosis-tech/kurtosis/issues/1077)) ([1d70382](https://github.com/kurtosis-tech/kurtosis/commit/1d70382cdefd5361da10c88c64a6c5be81ae3a57)) +* enable streaming exec output in container engine (stream exec pt. 1) ([#1043](https://github.com/kurtosis-tech/kurtosis/issues/1043)) ([e8f34ef](https://github.com/kurtosis-tech/kurtosis/commit/e8f34ef3d33cf84499ddb07b461ca87319bef0fc)) +* implement new logging architecture v0 ([#1071](https://github.com/kurtosis-tech/kurtosis/issues/1071)) ([c66c148](https://github.com/kurtosis-tech/kurtosis/commit/c66c1480c8f8e6fcc8e17488135ff3d1cb456ffa)) +* make enclave namespace and network naming deterministic ([#1100](https://github.com/kurtosis-tech/kurtosis/issues/1100)) ([0d42106](https://github.com/kurtosis-tech/kurtosis/commit/0d42106a015793f7a5d7ede06a54fac58767af7d)) +* Persist file artifacts ([#1084](https://github.com/kurtosis-tech/kurtosis/issues/1084)) ([c7b3590](https://github.com/kurtosis-tech/kurtosis/commit/c7b3590a121ef4a9398efe7a5bc479578a04c43f)) +* Portal automatic start and stop on context change ([#1086](https://github.com/kurtosis-tech/kurtosis/issues/1086)) ([a6a73d1](https://github.com/kurtosis-tech/kurtosis/commit/a6a73d1c2a03c9d6d9e89b689b86bf170e39f108)), closes [#970](https://github.com/kurtosis-tech/kurtosis/issues/970) +* Update files if already present in enclave ([#1066](https://github.com/kurtosis-tech/kurtosis/issues/1066)) ([1135543](https://github.com/kurtosis-tech/kurtosis/commit/1135543b1dea9ddb2f5419cffd9fd1557e644824)) + + +### Bug Fixes + +* Add API key to endpoint ([#1102](https://github.com/kurtosis-tech/kurtosis/issues/1102)) ([64f0c20](https://github.com/kurtosis-tech/kurtosis/commit/64f0c2034405fbaefb7dfb26f63308f055978f53)) +* Fix issue with idempotent plan resolution ([#1087](https://github.com/kurtosis-tech/kurtosis/issues/1087)) ([fd48f8f](https://github.com/kurtosis-tech/kurtosis/commit/fd48f8f5f34abe2929b7831ef1453b67eba0b3ca)) +* Forward the engine port after verifying that an engine container is running and before initializing the engine client ([#1099](https://github.com/kurtosis-tech/kurtosis/issues/1099)) ([b0b7a3b](https://github.com/kurtosis-tech/kurtosis/commit/b0b7a3b0fa5da07803d1d5b2697ca9805d8147d9)) +* update golang docker client to latest ([#1082](https://github.com/kurtosis-tech/kurtosis/issues/1082)) ([724084f](https://github.com/kurtosis-tech/kurtosis/commit/724084f1f0b6d0645990d7b92e41ad6e286f9259)) + +## [0.81.5](https://github.com/kurtosis-tech/kurtosis/compare/0.81.4...0.81.5) (2023-08-07) + + +### Features + +* Enclave inspect relying on the API container service only ([#1070](https://github.com/kurtosis-tech/kurtosis/issues/1070)) ([da171ea](https://github.com/kurtosis-tech/kurtosis/commit/da171ea6a9350992ec282265ecfa07882dc47c65)) + + +### Bug Fixes + +* Fix broken link in docs causing CI build to fail ([#1079](https://github.com/kurtosis-tech/kurtosis/issues/1079)) ([77d8a13](https://github.com/kurtosis-tech/kurtosis/commit/77d8a13e1104eb7b7556a2c3796a2ad5e51f23ec)) + +## [0.81.4](https://github.com/kurtosis-tech/kurtosis/compare/0.81.3...0.81.4) (2023-08-03) + + +### Bug Fixes + +* Only forward APIC port on remote context. ([#1049](https://github.com/kurtosis-tech/kurtosis/issues/1049)) ([7072b7b](https://github.com/kurtosis-tech/kurtosis/commit/7072b7be2fa0f5a417a3e0ca28c4ca8cb4558a29)), closes [#1039](https://github.com/kurtosis-tech/kurtosis/issues/1039) +* remove historical enclave names from auto complete ([#1059](https://github.com/kurtosis-tech/kurtosis/issues/1059)) ([e63fd88](https://github.com/kurtosis-tech/kurtosis/commit/e63fd88b8bc657f086b631400dd1c70b0f66d1ab)) + +## [0.81.3](https://github.com/kurtosis-tech/kurtosis/compare/0.81.2...0.81.3) (2023-08-03) + + +### Bug Fixes + +* Pin grpc-file-transfer version on Go SDK ([#1058](https://github.com/kurtosis-tech/kurtosis/issues/1058)) ([36a16ac](https://github.com/kurtosis-tech/kurtosis/commit/36a16ac3b6db9914f3b0a6695535d8ee6ac8ae6b)) + +## [0.81.2](https://github.com/kurtosis-tech/kurtosis/compare/0.81.1...0.81.2) (2023-08-03) + + +### Features + +* Compute content hash when compressing files artifact ([#1041](https://github.com/kurtosis-tech/kurtosis/issues/1041)) ([510ffe2](https://github.com/kurtosis-tech/kurtosis/commit/510ffe270fea663985b45228e45836fcb575932d)) + + +### Bug Fixes + +* Fix comment about sidecar ([#1053](https://github.com/kurtosis-tech/kurtosis/issues/1053)) ([d9b07ea](https://github.com/kurtosis-tech/kurtosis/commit/d9b07ea0a5d609c1191c7e7260a1928ddd1ebd4e)) +* Use the local grpc-file-transfer library version ([#1056](https://github.com/kurtosis-tech/kurtosis/issues/1056)) ([59fa980](https://github.com/kurtosis-tech/kurtosis/commit/59fa98013aee05a32a34aa2bef1a153a1a57a29b)) + +## [0.81.1](https://github.com/kurtosis-tech/kurtosis/compare/0.81.0...0.81.1) (2023-08-02) + + +### Features + +* Print execution steps for kurtosis import ([#1047](https://github.com/kurtosis-tech/kurtosis/issues/1047)) ([44d3b16](https://github.com/kurtosis-tech/kurtosis/commit/44d3b16528a8523f3c20842e373b3b51458fb267)) + + +### Bug Fixes + +* Stop local running engine when switching context ([#1040](https://github.com/kurtosis-tech/kurtosis/issues/1040)) ([a8b5606](https://github.com/kurtosis-tech/kurtosis/commit/a8b5606f445cb72126db2bca15efdb294c1d75a0)) + +## [0.81.0](https://github.com/kurtosis-tech/kurtosis/compare/0.80.24...0.81.0) (2023-08-02) + + +### ⚠ BREAKING CHANGES + +* subnetwork capabilities removed from Kurtosis. Users will have to update their Kurtosis package if they are using subnetwork capabilities ([#1038](https://github.com/kurtosis-tech/kurtosis/issues/1038)) + +### Features + +* subnetwork capabilities removed from Kurtosis. Users will have to update their Kurtosis package if they are using subnetwork capabilities ([#1038](https://github.com/kurtosis-tech/kurtosis/issues/1038)) ([724f713](https://github.com/kurtosis-tech/kurtosis/commit/724f713bd7271dffc10c78dfdc8f5c6c4d42af0d)) + +## [0.80.24](https://github.com/kurtosis-tech/kurtosis/compare/0.80.23...0.80.24) (2023-08-01) + + +### Features + +* Persistent directories for docker ([#1034](https://github.com/kurtosis-tech/kurtosis/issues/1034)) ([2f909c3](https://github.com/kurtosis-tech/kurtosis/commit/2f909c381c297c75558c9b17ce3974e1d6091b87)) +* Persistent directories for Kubernetes ([#1036](https://github.com/kurtosis-tech/kurtosis/issues/1036)) ([4488986](https://github.com/kurtosis-tech/kurtosis/commit/44889866922e728a633573414e5a9ae81310e7c1)) + + +### Bug Fixes + +* Remove the temp cert files only after the docker client is initialized ([#1030](https://github.com/kurtosis-tech/kurtosis/issues/1030)) ([1a6bb74](https://github.com/kurtosis-tech/kurtosis/commit/1a6bb747b99bd730cc7c214469d46fff3538fc5f)) + +## [0.80.23](https://github.com/kurtosis-tech/kurtosis/compare/0.80.22...0.80.23) (2023-07-31) + + +### Features + +* add `cloud add` ([#1015](https://github.com/kurtosis-tech/kurtosis/issues/1015)) ([48aecd0](https://github.com/kurtosis-tech/kurtosis/commit/48aecd05381b9b89fb34da145f9651605ca446d2)) + + +### Bug Fixes + +* Fix error swallowing in DefaultServiceNetwork.destroyService ([#987](https://github.com/kurtosis-tech/kurtosis/issues/987)) ([828f366](https://github.com/kurtosis-tech/kurtosis/commit/828f3666d4c0cb27cd83f071204e75143da14348)) + +## [0.80.22](https://github.com/kurtosis-tech/kurtosis/compare/0.80.21...0.80.22) (2023-07-28) + + +### Features + +* Add starlark converter to kurtosis import ([#1010](https://github.com/kurtosis-tech/kurtosis/issues/1010)) ([8554635](https://github.com/kurtosis-tech/kurtosis/commit/8554635af6990d1b152aa914ef2c595d5f8be802)) +* Support resource reservations on Docker compose import ([#1023](https://github.com/kurtosis-tech/kurtosis/issues/1023)) ([e7a5576](https://github.com/kurtosis-tech/kurtosis/commit/e7a5576e1a5dd96b4fdf0b9858caa9394b0572ef)) + + +### Bug Fixes + +* truncate output if greater than 64*1024 characters ([#1022](https://github.com/kurtosis-tech/kurtosis/issues/1022)) ([c3e8939](https://github.com/kurtosis-tech/kurtosis/commit/c3e8939811ea4ccafd559cfd9d3705350c6f9fac)) + +## [0.80.21](https://github.com/kurtosis-tech/kurtosis/compare/0.80.20...0.80.21) (2023-07-28) + + +### Bug Fixes + +* Check if a local engine is running before switching to a remote context and let the user know what to do ([#1011](https://github.com/kurtosis-tech/kurtosis/issues/1011)) ([141247f](https://github.com/kurtosis-tech/kurtosis/commit/141247f46fc5ca11644a35f865c737e96dd3a343)) +* fix cpu calculation by getting pre cpu stat ([52a191e](https://github.com/kurtosis-tech/kurtosis/commit/52a191e9e4a1cfaf011ef3b7c0d3d6ea02822756)) +* Implement GetEngineLogs in Kubernete backend ([#1005](https://github.com/kurtosis-tech/kurtosis/issues/1005)) ([3d0a3e2](https://github.com/kurtosis-tech/kurtosis/commit/3d0a3e2153da6254f62e53b9f03d9106c57e45a0)) +* Log streaming was timing out on docker ([#999](https://github.com/kurtosis-tech/kurtosis/issues/999)) ([d3b6c43](https://github.com/kurtosis-tech/kurtosis/commit/d3b6c434ee3229ba6f433fda5374c0676d690db0)) +* make continuity test work ([#1016](https://github.com/kurtosis-tech/kurtosis/issues/1016)) ([c430db2](https://github.com/kurtosis-tech/kurtosis/commit/c430db22616b0684711a79e4326a49102437abe6)) +* make resource fetching a parallel operation ([#1012](https://github.com/kurtosis-tech/kurtosis/issues/1012)) ([52a191e](https://github.com/kurtosis-tech/kurtosis/commit/52a191e9e4a1cfaf011ef3b7c0d3d6ea02822756)) +* only ask for emails on interactive terminals ([#1018](https://github.com/kurtosis-tech/kurtosis/issues/1018)) ([1bdac73](https://github.com/kurtosis-tech/kurtosis/commit/1bdac73eb07611cb6bcfd987ed4282b7eb06c26e)) + +## [0.80.20](https://github.com/kurtosis-tech/kurtosis/compare/0.80.19...0.80.20) (2023-07-27) + + +### Features + +* add `kurtosis cloud load to CLI` ([#882](https://github.com/kurtosis-tech/kurtosis/issues/882)) ([b2db8c9](https://github.com/kurtosis-tech/kurtosis/commit/b2db8c98d7b17c96d53c28154739e624fe48a63d)) +* ask user for email on first run of Kurtosis ([#1001](https://github.com/kurtosis-tech/kurtosis/issues/1001)) ([0f33b5b](https://github.com/kurtosis-tech/kurtosis/commit/0f33b5b4a3286d9f3a973ad55f7479f17a1782a6)) +* Start engine remotely with remote backend config when the context is remote ([#963](https://github.com/kurtosis-tech/kurtosis/issues/963)) ([6816d1f](https://github.com/kurtosis-tech/kurtosis/commit/6816d1f01d99e80609f808b57d2250ebc0b1c8bd)) +* validate min cpu & min memory are well under whats available ([#988](https://github.com/kurtosis-tech/kurtosis/issues/988)) ([768e95d](https://github.com/kurtosis-tech/kurtosis/commit/768e95d2dbeb7a554a97cff8b6650e734dccd66a)) + + +### Bug Fixes + +* Normalize destroy enclave in all tests ([#976](https://github.com/kurtosis-tech/kurtosis/issues/976)) ([20b635a](https://github.com/kurtosis-tech/kurtosis/commit/20b635a2fc7efc958e7bd7e007b2db65762b8b1c)) + +## [0.80.19](https://github.com/kurtosis-tech/kurtosis/compare/0.80.18...0.80.19) (2023-07-26) + + +### Bug Fixes + +* Fix docker image pull hanging forever ([#994](https://github.com/kurtosis-tech/kurtosis/issues/994)) ([fd00d79](https://github.com/kurtosis-tech/kurtosis/commit/fd00d79efca2a7d8b3b04ce9d1f4d988dc1d956b)) + +## [0.80.18](https://github.com/kurtosis-tech/kurtosis/compare/0.80.17...0.80.18) (2023-07-26) + + +### Features + +* Add volume bind support for `kurtosis import` ([#984](https://github.com/kurtosis-tech/kurtosis/issues/984)) ([391c016](https://github.com/kurtosis-tech/kurtosis/commit/391c016ccaa24d454f746179bd096030596bf363)) + + +### Bug Fixes + +* CLI args marked as greedy were not greedy ([#975](https://github.com/kurtosis-tech/kurtosis/issues/975)) ([e6ff482](https://github.com/kurtosis-tech/kurtosis/commit/e6ff482cdf6758885ae9a1bdcd3ea6fb5e620a05)) + +## [0.80.17](https://github.com/kurtosis-tech/kurtosis/compare/0.80.16...0.80.17) (2023-07-26) + + +### Features + +* Add `environment` support for `kurtosis import` ([#982](https://github.com/kurtosis-tech/kurtosis/issues/982)) ([24e71d1](https://github.com/kurtosis-tech/kurtosis/commit/24e71d1464b9d081056d61f43fde09fba2d8505f)), closes [#981](https://github.com/kurtosis-tech/kurtosis/issues/981) + +## [0.80.16](https://github.com/kurtosis-tech/kurtosis/compare/0.80.15...0.80.16) (2023-07-25) + + +### Features + +* folks can now use frontend to view file artifacts and it's content. ([#967](https://github.com/kurtosis-tech/kurtosis/issues/967)) ([fc87c31](https://github.com/kurtosis-tech/kurtosis/commit/fc87c31cd8deecfcba689ef0d0416be017f9ff36)) + +## [0.80.15](https://github.com/kurtosis-tech/kurtosis/compare/0.80.14...0.80.15) (2023-07-25) + + +### Features + +* Implement V0 of docker import ([#968](https://github.com/kurtosis-tech/kurtosis/issues/968)) ([6f8d90d](https://github.com/kurtosis-tech/kurtosis/commit/6f8d90d526293f676e50243d52aa132ea74447bd)) + + +### Bug Fixes + +* Run user service containers in --init mode for Docker ([#965](https://github.com/kurtosis-tech/kurtosis/issues/965)) ([b8989a8](https://github.com/kurtosis-tech/kurtosis/commit/b8989a8112e4f25fed0e595d32a28c45a58a8b1b)) + +## [0.80.14](https://github.com/kurtosis-tech/kurtosis/compare/0.80.13...0.80.14) (2023-07-24) + + +### Features + +* Add ability to update a running service ([#943](https://github.com/kurtosis-tech/kurtosis/issues/943)) ([42a67f9](https://github.com/kurtosis-tech/kurtosis/commit/42a67f9a3f9d4413f58929867b4e6e61eeeaa25e)) +* added create enclave flow ([#962](https://github.com/kurtosis-tech/kurtosis/issues/962)) ([4c931b8](https://github.com/kurtosis-tech/kurtosis/commit/4c931b882e4298cf8d99d88425b0323576f7baf5)) +* Idempotent run V1 - services can now be live-updated inside an enclave ([#954](https://github.com/kurtosis-tech/kurtosis/issues/954)) ([a6a118d](https://github.com/kurtosis-tech/kurtosis/commit/a6a118d5b6cc0d3560a5e3abdd8b043397efeced)) + + +### Bug Fixes + +* Fix `successfully executed` bug in APIC logs when script fails ([#964](https://github.com/kurtosis-tech/kurtosis/issues/964)) ([32fe63f](https://github.com/kurtosis-tech/kurtosis/commit/32fe63fcb77a8db78b2e1e86be18d3857bfa5fc0)) +* no magic string replacement in python packages ([#966](https://github.com/kurtosis-tech/kurtosis/issues/966)) ([8b0fa62](https://github.com/kurtosis-tech/kurtosis/commit/8b0fa623a2c73ec195e2204da5a8463e016e6833)) +* the old go download ([#958](https://github.com/kurtosis-tech/kurtosis/issues/958)) ([f1b52ca](https://github.com/kurtosis-tech/kurtosis/commit/f1b52ca98215f090a849e626f934ccd341ad91c3)) + +## [0.80.13](https://github.com/kurtosis-tech/kurtosis/compare/0.80.12...0.80.13) (2023-07-20) + + +### Features + +* Add autocomplete for file path of artifact files inspect ([#947](https://github.com/kurtosis-tech/kurtosis/issues/947)) ([f72dfce](https://github.com/kurtosis-tech/kurtosis/commit/f72dfce9b755c37dde849f9047ef4a6ca7e59cb2)) + + +### Bug Fixes + +* broken symlinks on Kurtosis packages ([#944](https://github.com/kurtosis-tech/kurtosis/issues/944)) ([fbb0aee](https://github.com/kurtosis-tech/kurtosis/commit/fbb0aee6edfce4598b0384aebfe71b1e12b9730c)), closes [#846](https://github.com/kurtosis-tech/kurtosis/issues/846) +* improve frontend ([#940](https://github.com/kurtosis-tech/kurtosis/issues/940)) ([36153e2](https://github.com/kurtosis-tech/kurtosis/commit/36153e2c6e3c332508d6071d2f9101f77cfb6295)) +* improved error msg ([#936](https://github.com/kurtosis-tech/kurtosis/issues/936)) ([4f72ae1](https://github.com/kurtosis-tech/kurtosis/commit/4f72ae12409d6ddd8c2e2c6b61770081d9200bde)) + +## [0.80.12](https://github.com/kurtosis-tech/kurtosis/compare/0.80.11...0.80.12) (2023-07-18) + + +### Features + +* Service count can go up to 1024 in Docker backend ([#919](https://github.com/kurtosis-tech/kurtosis/issues/919)) ([e1dfff1](https://github.com/kurtosis-tech/kurtosis/commit/e1dfff119a0b6635e732e0e09de68b56d6af7d63)) + +## [0.80.11](https://github.com/kurtosis-tech/kurtosis/compare/0.80.10...0.80.11) (2023-07-18) + + +### Features + +* Add file artifact inspect API do APIC ([#885](https://github.com/kurtosis-tech/kurtosis/issues/885)) ([7ad8155](https://github.com/kurtosis-tech/kurtosis/commit/7ad81553a8056887e1399649536319922a05bdc1)) +* Add file inspect command to the CLI ([#905](https://github.com/kurtosis-tech/kurtosis/issues/905)) ([bb36a46](https://github.com/kurtosis-tech/kurtosis/commit/bb36a469925c3a8c00a88c0f5a16995088d26548)) +* added run python ([#913](https://github.com/kurtosis-tech/kurtosis/issues/913)) ([365f5cf](https://github.com/kurtosis-tech/kurtosis/commit/365f5cf15399dd0e79f7b82d5ab4ad823def00b5)) +* upload files support relative locators ([#930](https://github.com/kurtosis-tech/kurtosis/issues/930)) ([8d60968](https://github.com/kurtosis-tech/kurtosis/commit/8d609686ce78a72f82455592b48eeab94b44c359)) + + +### Bug Fixes + +* make service labels more restrictive ([#929](https://github.com/kurtosis-tech/kurtosis/issues/929)) ([a8fb599](https://github.com/kurtosis-tech/kurtosis/commit/a8fb5992d0e60bc50efa8585393048c168e878f0)), closes [#928](https://github.com/kurtosis-tech/kurtosis/issues/928) + +## [0.80.10](https://github.com/kurtosis-tech/kurtosis/compare/0.80.9...0.80.10) (2023-07-17) + + +### Features + +* Added enclave pool for improving performance on enclave creation ([#787](https://github.com/kurtosis-tech/kurtosis/issues/787)) ([d6efa43](https://github.com/kurtosis-tech/kurtosis/commit/d6efa435efeb9989de8f20f1d2d80603b7ef6827)) + +## [0.80.9](https://github.com/kurtosis-tech/kurtosis/compare/0.80.8...0.80.9) (2023-07-17) + + +### Features + +* added a command that opens the Kurtosis Web UI ([#870](https://github.com/kurtosis-tech/kurtosis/issues/870)) ([5098969](https://github.com/kurtosis-tech/kurtosis/commit/509896934656161002d674fa7c61ccd32c6f899d)) +* allow for relative imports from packages ([#891](https://github.com/kurtosis-tech/kurtosis/issues/891)) ([42bedab](https://github.com/kurtosis-tech/kurtosis/commit/42bedab9d45e4988f019dea7ccb2985f058e8199)) +* Autocomplete file artifact name on download ([#910](https://github.com/kurtosis-tech/kurtosis/issues/910)) ([2cedd08](https://github.com/kurtosis-tech/kurtosis/commit/2cedd0802a8595c3b299cb844fb42e3495991114)) +* Make output directory optional for files download ([#909](https://github.com/kurtosis-tech/kurtosis/issues/909)) ([2543d9a](https://github.com/kurtosis-tech/kurtosis/commit/2543d9ad9c68b86c1c1f09137ca60ddfce785b22)) +* Starlark package arguments will be parsed as a deep Struct when `"_kurtosis_parser": "struct"` is passed in the arguments JSON ([#884](https://github.com/kurtosis-tech/kurtosis/issues/884)) ([39ec8c2](https://github.com/kurtosis-tech/kurtosis/commit/39ec8c2d4a867420a76119523eb302dc652adb9b)) +* updated golang api sdk to 1.19 ([#908](https://github.com/kurtosis-tech/kurtosis/issues/908)) ([fabbb1c](https://github.com/kurtosis-tech/kurtosis/commit/fabbb1cde6b827ef2255bf184356b2f8a3ba9fbf)) + + +### Bug Fixes + +* fixed the log and file artifact issue ([#890](https://github.com/kurtosis-tech/kurtosis/issues/890)) ([7f7fe7b](https://github.com/kurtosis-tech/kurtosis/commit/7f7fe7b2d5dc91ddaa8b088129c5be8de0d9f396)) +* pinned go version to 1.19.10 for now ([#907](https://github.com/kurtosis-tech/kurtosis/issues/907)) ([847a37c](https://github.com/kurtosis-tech/kurtosis/commit/847a37c756b50588a567459956f49fcd26d99c28)) + +## [0.80.8](https://github.com/kurtosis-tech/kurtosis/compare/0.80.7...0.80.8) (2023-07-11) + + +### Features + +* auto assign docs issue to karla ([#834](https://github.com/kurtosis-tech/kurtosis/issues/834)) ([7d0a245](https://github.com/kurtosis-tech/kurtosis/commit/7d0a245fcac4043ab5b780248080b4832b1b0cfe)) +* exposing kurtosis frontend v0 ([#833](https://github.com/kurtosis-tech/kurtosis/issues/833)) ([110e910](https://github.com/kurtosis-tech/kurtosis/commit/110e9100ddc69244e7c317ab1e979e15de9f8863)) +* Make Run also accept argument other than args dict ([#859](https://github.com/kurtosis-tech/kurtosis/issues/859)) ([9fce411](https://github.com/kurtosis-tech/kurtosis/commit/9fce4112764dfdb135e066e2f54b954f79664b50)) + + +### Bug Fixes + +* fixed the output for port print ([#816](https://github.com/kurtosis-tech/kurtosis/issues/816)) ([ede32e7](https://github.com/kurtosis-tech/kurtosis/commit/ede32e795b77387d46ba49e37a6ccc0947fba79a)) + +## [0.80.7](https://github.com/kurtosis-tech/kurtosis/compare/0.80.6...0.80.7) (2023-07-05) + + +### Bug Fixes + +* Remove existing package directory if it already exists in APIC ([#818](https://github.com/kurtosis-tech/kurtosis/issues/818)) ([4027485](https://github.com/kurtosis-tech/kurtosis/commit/4027485d20917729eb1271387be1317af89ff025)) + +## [0.80.6](https://github.com/kurtosis-tech/kurtosis/compare/0.80.5...0.80.6) (2023-07-04) + + +### Features + +* Invert USE_INSTRUCTIONS_CACHING feature flag ([#800](https://github.com/kurtosis-tech/kurtosis/issues/800)) ([9a358db](https://github.com/kurtosis-tech/kurtosis/commit/9a358db49d4d222db4c45de62c70e190c6fa7c12)) + + +### Bug Fixes + +* fallback to the amd64 image if there's a failure for arm64 image not existing ([#814](https://github.com/kurtosis-tech/kurtosis/issues/814)) ([9cc1033](https://github.com/kurtosis-tech/kurtosis/commit/9cc10332fd67dbe060b883296c7efe5284130b12)) + +## [0.80.5](https://github.com/kurtosis-tech/kurtosis/compare/0.80.4...0.80.5) (2023-06-30) + + +### Bug Fixes + +* Fix TS proto bindings ([#797](https://github.com/kurtosis-tech/kurtosis/issues/797)) ([7958dba](https://github.com/kurtosis-tech/kurtosis/commit/7958dba5cec3dfb09eb69f24785d33dbd94051d6)) +* make dry run return the right return value ([#795](https://github.com/kurtosis-tech/kurtosis/issues/795)) ([be5f6e7](https://github.com/kurtosis-tech/kurtosis/commit/be5f6e75229a3887dc84c7a139aebe84b09fc77d)) +* More informative logging for instructions caching ([#785](https://github.com/kurtosis-tech/kurtosis/issues/785)) ([376ac8c](https://github.com/kurtosis-tech/kurtosis/commit/376ac8ceb7085a744c5cf84756b5d2c72a2577f7)) + +## [0.80.4](https://github.com/kurtosis-tech/kurtosis/compare/0.80.3...0.80.4) (2023-06-28) + + +### Features + +* make the docker network attachable ([#788](https://github.com/kurtosis-tech/kurtosis/issues/788)) ([aeb0b9f](https://github.com/kurtosis-tech/kurtosis/commit/aeb0b9f06749ac42b132f292bc4e24d2b177d472)) + +## [0.80.3](https://github.com/kurtosis-tech/kurtosis/compare/0.80.2...0.80.3) (2023-06-27) + + +### Features + +* Add minimal support for feature flags in APIC ([#775](https://github.com/kurtosis-tech/kurtosis/issues/775)) ([0858f56](https://github.com/kurtosis-tech/kurtosis/commit/0858f5685365e7d0ab032f362d5ce402c7e5e888)) +* added port print functionality in cli for users to quickly check how to access port. ([#778](https://github.com/kurtosis-tech/kurtosis/issues/778)) ([477510b](https://github.com/kurtosis-tech/kurtosis/commit/477510b801a90fce9fcc5bdc403bccc81d505201)) +* Implement idempotent run v0 ([#769](https://github.com/kurtosis-tech/kurtosis/issues/769)) ([23b121f](https://github.com/kurtosis-tech/kurtosis/commit/23b121f6ec4e956aa3d1125eeb47bffdb8c136aa)) +* Stop and start service support in the CLI ([#767](https://github.com/kurtosis-tech/kurtosis/issues/767)) ([cd4ca05](https://github.com/kurtosis-tech/kurtosis/commit/cd4ca05d17c07892b494b44f23f4c61b1b15d948)), closes [#705](https://github.com/kurtosis-tech/kurtosis/issues/705) + +## [0.80.2](https://github.com/kurtosis-tech/kurtosis/compare/0.80.1...0.80.2) (2023-06-26) + + +### Features + +* Add cargo build as part of Kurtosis build ([#774](https://github.com/kurtosis-tech/kurtosis/issues/774)) ([c68fe0a](https://github.com/kurtosis-tech/kurtosis/commit/c68fe0a44c331e72e58762a420fdbc6ec947c9f7)) + +## [0.80.1](https://github.com/kurtosis-tech/kurtosis/compare/0.80.0...0.80.1) (2023-06-26) + + +### Features + +* Add Rust protobuf bindings ([#765](https://github.com/kurtosis-tech/kurtosis/issues/765)) ([0e47003](https://github.com/kurtosis-tech/kurtosis/commit/0e47003c9f001e31b7a18bc6ea0ddb1d330f0acb)) +* added wait to run_sh task. ([#750](https://github.com/kurtosis-tech/kurtosis/issues/750)) ([8c2b697](https://github.com/kurtosis-tech/kurtosis/commit/8c2b697548f06c1f7e8a1474e9ee2cb2922d5dea)) +* Implemented rename enclave method in container engine lib ([#755](https://github.com/kurtosis-tech/kurtosis/issues/755)) ([f1570f7](https://github.com/kurtosis-tech/kurtosis/commit/f1570f7e050109c41676e0b9b3aa6b7f251d24ee)) +* Persist enclave plan in the Starlark executor memory ([#757](https://github.com/kurtosis-tech/kurtosis/issues/757)) ([2c3d74e](https://github.com/kurtosis-tech/kurtosis/commit/2c3d74e9c88e6b3a980048b6831b23499b4a0a12)) +* Start and Stop service Starlark instructions for K8S ([#756](https://github.com/kurtosis-tech/kurtosis/issues/756)) ([fb3e922](https://github.com/kurtosis-tech/kurtosis/commit/fb3e92215fa8062d3a08d1e71ab8572129785688)) + + +### Bug Fixes + +* Fix TestStarlarkRemotePackage E2E test to reflect new quickstart ([#773](https://github.com/kurtosis-tech/kurtosis/issues/773)) ([e4dd53f](https://github.com/kurtosis-tech/kurtosis/commit/e4dd53f47ebb6b2efff00b50f035f030169396e5)) + +## [0.80.0](https://github.com/kurtosis-tech/kurtosis/compare/0.79.0...0.80.0) (2023-06-21) + + +### ⚠ BREAKING CHANGES + +* Applying RFC-1123 standard to service names ([#749](https://github.com/kurtosis-tech/kurtosis/issues/749)) + +### Features + +* Applying RFC-1123 standard to service names ([#749](https://github.com/kurtosis-tech/kurtosis/issues/749)) ([66a5ebe](https://github.com/kurtosis-tech/kurtosis/commit/66a5ebe922559c4d7b8d10b7f7870af6d1700c6b)) + +## [0.79.0](https://github.com/kurtosis-tech/kurtosis/compare/0.78.5...0.79.0) (2023-06-21) + + +### ⚠ BREAKING CHANGES + +* removed workdir from run_sh and fixed some typos on the doc ([#739](https://github.com/kurtosis-tech/kurtosis/issues/739)) + +### Features + +* allow to pop a shell on Kubernetes ([#748](https://github.com/kurtosis-tech/kurtosis/issues/748)) ([3c706e5](https://github.com/kurtosis-tech/kurtosis/commit/3c706e54f06f60c3950f9c46654ac05b54014dbf)) + + +### Bug Fixes + +* removed workdir from run_sh and fixed some typos on the doc ([#739](https://github.com/kurtosis-tech/kurtosis/issues/739)) ([6406f10](https://github.com/kurtosis-tech/kurtosis/commit/6406f10bb1a96cdce429d2c4750977fb86f2d098)) +* Support for reconnects in the Gateway port forwarder ([#736](https://github.com/kurtosis-tech/kurtosis/issues/736)) ([4944ccd](https://github.com/kurtosis-tech/kurtosis/commit/4944ccdf32a36786be8816c7e425c08ceccebc9c)), closes [#726](https://github.com/kurtosis-tech/kurtosis/issues/726) +* typos ([#742](https://github.com/kurtosis-tech/kurtosis/issues/742)) ([800e523](https://github.com/kurtosis-tech/kurtosis/commit/800e52364bc62f1dfa1b48bdcae9b01d4d2af7fe)) + +## [0.78.5](https://github.com/kurtosis-tech/kurtosis/compare/0.78.4...0.78.5) (2023-06-15) + + +### Features + +* added ability for folks to copy files from the one time execution task ([#723](https://github.com/kurtosis-tech/kurtosis/issues/723)) ([f1fcde1](https://github.com/kurtosis-tech/kurtosis/commit/f1fcde148fffe81bc15ea7ab62b00ecd0099e172)) +* added run_sh to vscode plugin ([#738](https://github.com/kurtosis-tech/kurtosis/issues/738)) ([337c994](https://github.com/kurtosis-tech/kurtosis/commit/337c9941f6686b2bf7b50416ee7fe71460a8aade)) +* Automatically inject the plan object if the first argument of the main function is `plan` ([#716](https://github.com/kurtosis-tech/kurtosis/issues/716)) ([142ce42](https://github.com/kurtosis-tech/kurtosis/commit/142ce42e5a349f468b5ebcbe9ec5f9a752825117)) + + +### Bug Fixes + +* Stopping engine not required before switching cluster ([#727](https://github.com/kurtosis-tech/kurtosis/issues/727)) ([af675c1](https://github.com/kurtosis-tech/kurtosis/commit/af675c13a2bcbb10e2619ce513b3c49efa7f642c)) + +## [0.78.4](https://github.com/kurtosis-tech/kurtosis/compare/0.78.3...0.78.4) (2023-06-13) + + +### Features + +* added run_sh instruction; users can run one time bash task ([#717](https://github.com/kurtosis-tech/kurtosis/issues/717)) ([566144a](https://github.com/kurtosis-tech/kurtosis/commit/566144a5c3cb73f8dc7b8aa13ffb20b9a802edfc)) + +## [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)) + + +### Bug Fixes + +* add `continue` to avoid segfault on service failing to register ([#719](https://github.com/kurtosis-tech/kurtosis/issues/719)) ([0cebb1f](https://github.com/kurtosis-tech/kurtosis/commit/0cebb1fe22ffd0e0e5e532164c3b0ef658b3ee55)) + +## [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.83.1/cli-reference/analytics-disable.md b/docs/versioned_docs/version-0.83.1/cli-reference/analytics-disable.md new file mode 100644 index 0000000000..bdd752902d --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/analytics-enable.md b/docs/versioned_docs/version-0.83.1/cli-reference/analytics-enable.md new file mode 100644 index 0000000000..318590a710 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/analytics-id.md b/docs/versioned_docs/version-0.83.1/cli-reference/analytics-id.md new file mode 100644 index 0000000000..6b2a60a0a3 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/clean.md b/docs/versioned_docs/version-0.83.1/cli-reference/clean.md new file mode 100644 index 0000000000..8bcbe8f54d --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/cluster-get.md b/docs/versioned_docs/version-0.83.1/cli-reference/cluster-get.md new file mode 100644 index 0000000000..3345924106 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/cluster-get.md @@ -0,0 +1,34 @@ +--- +title: cluster get +sidebar_label: cluster get +slug: /cluster-get +--- + +Kurtosis will work locally or over remote infrastructure. To determine the type of infrastructure your instance of Kurtosis is running on, simply run: + +```bash +kurtosis cluster get +``` + +The clusters that Kurtosis can connect to are defined in your `kurtosis-config.yml` file, located at `/Users//Library/Application Support/kurtosis/kurtosis-config.yml` on MacOS. See [this guide](https://docs.kurtosis.com/k8s#iii-add-your-cluster-information-to-kurtosis-configyml) to learn more about how to add cluster information to your `kurtosis-config.yml` file. + +Below is an example of what a valid `kurtosis-config.yml` file might look like with the clusters: `docker`, `minikube`, and `cloud`: +```yml +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 +``` \ No newline at end of file diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/cluster-ls.md b/docs/versioned_docs/version-0.83.1/cli-reference/cluster-ls.md new file mode 100644 index 0000000000..8c5cf519ef --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/cluster-ls.md @@ -0,0 +1,34 @@ +--- +title: cluster ls +sidebar_label: cluster ls +slug: /cluster-ls +--- + +To list all valid clusters that Kurtosis can connect to (as defined in your `kurtosis-config.yml`), simply run: + +```bash +kurtosis cluster ls +``` + +The clusters that Kurtosis can connect to are defined in your `kurtosis-config.yml` file, located at `/Users//Library/Application Support/kurtosis/kurtosis-config.yml` on MacOS. See [this guide](https://docs.kurtosis.com/k8s#iii-add-your-cluster-information-to-kurtosis-configyml) to learn more about how to add cluster information to your `kurtosis-config.yml` file. + +Below is an example of what a valid `kurtosis-config.yml` file might look like with the clusters: `docker`, `minikube`, and `cloud`: +```yml +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 +``` \ No newline at end of file diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/cluster-set.md b/docs/versioned_docs/version-0.83.1/cli-reference/cluster-set.md new file mode 100644 index 0000000000..7fc0d94e1f --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/cluster-set.md @@ -0,0 +1,34 @@ +--- +title: cluster set +sidebar_label: cluster set +slug: /cluster-set +--- + +To set the cluster for your instance of Kurtosis, simply run: + +```bash +kurtosis cluster set $NAME_OF_CLUSTER +``` + +Where the `$NAME_OF_CLUSTER` argument is the name of a Kurtosis cluster defined in your `kurtosis-config.yml` (located at `/Users//Library/Application Support/kurtosis/kurtosis-config.yml` on MacOS). See [this guide](https://docs.kurtosis.com/k8s#iii-add-your-cluster-information-to-kurtosis-configyml) to learn more about how to add cluster information to your `kurtosis-config.yml` file. + +Below is an example of what a valid `kurtosis-config.yml` file might look like with the clusters: `docker`, `minikube`, and `cloud`: +```yml +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 +``` \ No newline at end of file diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/completion.md b/docs/versioned_docs/version-0.83.1/cli-reference/completion.md new file mode 100644 index 0000000000..2891eaa291 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/config-path.md b/docs/versioned_docs/version-0.83.1/cli-reference/config-path.md new file mode 100644 index 0000000000..9f72383027 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/config-path.md @@ -0,0 +1,13 @@ +--- +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. + +To see the full set of configuration values available: + +1. Open [the directory containing the versions of Kurtosis config](https://github.com/kurtosis-tech/kurtosis/tree/main/cli/cli/kurtosis_config/overrides_objects) +2. Select the most recent (highest) version +3. Explore the various config objects inside, starting with the `kurtosis_config_vX.go` top-level object (each `struct` represents a YAML object inside the configuration) diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/discord.md b/docs/versioned_docs/version-0.83.1/cli-reference/discord.md new file mode 100644 index 0000000000..291f08cb4b --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/docs.md b/docs/versioned_docs/version-0.83.1/cli-reference/docs.md new file mode 100644 index 0000000000..a41e0ee2af --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/dump.md b/docs/versioned_docs/version-0.83.1/cli-reference/dump.md new file mode 100644 index 0000000000..0cb0d36628 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/enclave-add.md b/docs/versioned_docs/version-0.83.1/cli-reference/enclave-add.md new file mode 100644 index 0000000000..ef965ddfdc --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/enclave-add.md @@ -0,0 +1,16 @@ +--- +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 +``` + +1. The `--production` flag can be used to make sure services restart in case of failure (default behavior is not restart) + + +[enclaves-reference]: ../concepts-reference/enclaves.md diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/enclave-dump.md b/docs/versioned_docs/version-0.83.1/cli-reference/enclave-dump.md new file mode 100644 index 0000000000..fa6a0e5168 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/enclave-inspect.md b/docs/versioned_docs/version-0.83.1/cli-reference/enclave-inspect.md new file mode 100644 index 0000000000..6eefaec664 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/enclave-ls.md b/docs/versioned_docs/version-0.83.1/cli-reference/enclave-ls.md new file mode 100644 index 0000000000..efc139ee95 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/enclave-rm.md b/docs/versioned_docs/version-0.83.1/cli-reference/enclave-rm.md new file mode 100644 index 0000000000..7b9361433d --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/enclave-stop.md b/docs/versioned_docs/version-0.83.1/cli-reference/enclave-stop.md new file mode 100644 index 0000000000..0fff1dea13 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/engine-logs.md b/docs/versioned_docs/version-0.83.1/cli-reference/engine-logs.md new file mode 100644 index 0000000000..96439f3242 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/engine-restart.md b/docs/versioned_docs/version-0.83.1/cli-reference/engine-restart.md new file mode 100644 index 0000000000..7ed0750d0f --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/engine-restart.md @@ -0,0 +1,18 @@ +--- +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 +``` + +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. +* `--enclave-pool-size`: The size of the Kurtosis engine enclave pool. The enclave pool is a component of the Kurtosis engine that allows us to create and maintain 'n' number of idle enclaves for future use. This functionality allows to improve the performance for each new creation enclave request. + +CAUTION: The `--enclave-pool-size` flag is only available for Kubernetes. \ No newline at end of file diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/engine-start.md b/docs/versioned_docs/version-0.83.1/cli-reference/engine-start.md new file mode 100644 index 0000000000..0c2b428be0 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/engine-start.md @@ -0,0 +1,19 @@ +--- +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. +* `--enclave-pool-size`: The size of the Kurtosis engine enclave pool. The enclave pool is a component of the Kurtosis engine that allows us to create and maintain 'n' number of idle enclaves for future use. This functionality allows to improve the performance for each new creation enclave request. + +CAUTION: The `--enclave-pool-size` flag is only available for Kubernetes. \ No newline at end of file diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/engine-status.md b/docs/versioned_docs/version-0.83.1/cli-reference/engine-status.md new file mode 100644 index 0000000000..537660351a --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/engine-stop.md b/docs/versioned_docs/version-0.83.1/cli-reference/engine-stop.md new file mode 100644 index 0000000000..80a222e0c7 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/feedback.md b/docs/versioned_docs/version-0.83.1/cli-reference/feedback.md new file mode 100644 index 0000000000..a8acd6661d --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/files-download.md b/docs/versioned_docs/version-0.83.1/cli-reference/files-download.md new file mode 100644 index 0000000000..fa40f69cc8 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/files-rendertemplate.md b/docs/versioned_docs/version-0.83.1/cli-reference/files-rendertemplate.md new file mode 100644 index 0000000000..42a19f02ef --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/files-storeservice.md b/docs/versioned_docs/version-0.83.1/cli-reference/files-storeservice.md new file mode 100644 index 0000000000..1564154d78 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/files-storeweb.md b/docs/versioned_docs/version-0.83.1/cli-reference/files-storeweb.md new file mode 100644 index 0000000000..3e676e515d --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/files-upload.md b/docs/versioned_docs/version-0.83.1/cli-reference/files-upload.md new file mode 100644 index 0000000000..4875cd6694 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/index.md b/docs/versioned_docs/version-0.83.1/cli-reference/index.md new file mode 100644 index 0000000000..fcaae662cf --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/port-print.md b/docs/versioned_docs/version-0.83.1/cli-reference/port-print.md new file mode 100644 index 0000000000..9c73ff602f --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/port-print.md @@ -0,0 +1,12 @@ +--- +title: port print +sidebar_label: port print +slug: /port-print +--- + +To print information about the PortSpec for Service, run: + +```bash +kurtosis port print $THE_ENCLAVE_IDENTIFIER $THE_SERVICE_IDENTIFIER $PORT_ID +``` +where `$THE_ENCLAVE_IDENTIFIER` and the `$THE_SERVICE_IDENTIFIER` are [resource identifiers](../concepts-reference/resource-identifier.md) for the enclave and service, respectively. The `$PORT_ID` is the unique port identifier assigned to the port using [`ServiceConfig`](../starlark-reference/service-config.md) on starlark. \ No newline at end of file diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/run.md b/docs/versioned_docs/version-0.83.1/cli-reference/run.md new file mode 100644 index 0000000000..5c641ff534 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/run.md @@ -0,0 +1,123 @@ +--- +title: run +sidebar_label: run +slug: /run +--- + +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 [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 + +Package behaviour can be customized by passing in JSON-serialized arguments when calling `kurtosis run`. + +For example, if your package's `run` function looks like this... + +```python +def run(plan, some_parameter, some_other_parameter="Default value"): +``` + +...then you can pass in values for `some_parameter` and `some_other_parameter` like so: + +```bash +kurtosis run github.com/USERNAME/REPO '{"some_parameter": 5, "some_other_parameter": "New value"}' +``` + +Kurtosis deserializes the JSON, with each key treated as a separate parameter passed to the `run` function in Starlark. + +This is the equivalent to the following Starlark: + +```python +run(plan, some_parameter = 5, some_other_parameter = "New value") +``` + +:::info +By default, Kurtosis deserializes JSON objects (anything in `{}`) as dictionaries in Starlark. However, sometimes you need to pass a `struct` as a parameter instead. + +To have Kurtosis deserialize a JSON object as a `struct` instead of a dictionary, simply add `"_kurtosis_parser": "struct"` to the object. + +For example, this command... + +```bash +kurtosis run github.com/USERNAME/REPO '{"some_parameter": {"_kurtosis_parser": "struct", "some_property": "Property value"}}' +``` + +...is equivalent to this Starlark: + +```python +run(plan, some_parameter = struct(some_property = "Property value")) +``` +::: + +### Extra Configuration + +`kurtosis run` has additional flags that can further modify its behaviour: + +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 `--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-function-name` flag can be used to set the name of Starlark function inside the package that `kurtosis run` will call. The default value is `run`, meaning Starlark will look for a function called `run` in the file defined by the `--main-file` flag (which defaults to `main.star`). Regardless of the function, Kurtosis expects the main function to have a parameter called `plan` into which Kurtosis will inject [the Kurtosis plan](../concepts-reference/plan.md). + + 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` like so: + ```python + # --------------- main.star -------------------- + def start_node(plan, args): + # your code + ``` +1. The `--main-file` flag sets the main file in which Kurtosis looks for the main function defined via the `--main-function-name` flag. This can be thought of as the entrypoint file. This flag takes a filepath **relative to the package's root**, and defaults to `main.star`. For example, if your package is `github.com/my-org/my-package` but your main file is located in subdirectories like `github.com/my-org/my-package/src/internal/my-file.star`, you should set this flag like `--main-file src/internal/my-file.star`. + + Example of using 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` like so: + + ```python + # main.star code + def start_node(plan,args): + # your code + ``` +1. The `--production` flag can be used to make sure services restart in case of failure (default behavior is not restart) + +1. The `--no-connect` flag can be used to disable user services port forwarding (default behavior is to forward the ports) + +1. The `--experimental` flag can be used to enable experimental or incubating features. Please reach out to Kurtosis team if you wish to try any of those. + + + +[add-services-reference]: ../starlark-reference/plan.md#add_services diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/service-add.md b/docs/versioned_docs/version-0.83.1/cli-reference/service-add.md new file mode 100644 index 0000000000..6632eab1ec --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/service-add.md @@ -0,0 +1,27 @@ +--- +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. +Note, the service identifier needs to be formatted according to RFC 1035. Specifically, 1-63 lowercase alphanumeric characters with dashes and cannot start or end with dashes. Also service names +have to start with a lowercase alphabet. + +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'" +``` diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/service-exec.md b/docs/versioned_docs/version-0.83.1/cli-reference/service-exec.md new file mode 100644 index 0000000000..2548f9061f --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/service-logs.md b/docs/versioned_docs/version-0.83.1/cli-reference/service-logs.md new file mode 100644 index 0000000000..25d07a1eb1 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/service-logs.md @@ -0,0 +1,25 @@ +--- +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. + +:::note Number of log lines +By default, logs printed in the terminal from this command are truncated at 200 lines. For a stream of logs, we recommend the `-f` flag. For a snapshot of the logs at a given point in time (e.g. after a change), we recommend the [`kurtosis dump`](./dump.md). +::: + +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. diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/service-rm.md b/docs/versioned_docs/version-0.83.1/cli-reference/service-rm.md new file mode 100644 index 0000000000..0b9f918e0b --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/service-rm.md @@ -0,0 +1,15 @@ +--- +title: service rm +sidebar_label: service rm +slug: /service-rm +--- + +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.83.1/cli-reference/service-shell.md b/docs/versioned_docs/version-0.83.1/cli-reference/service-shell.md new file mode 100644 index 0000000000..4f964b0120 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/service-start.md b/docs/versioned_docs/version-0.83.1/cli-reference/service-start.md new file mode 100644 index 0000000000..10b0c04a7c --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/service-start.md @@ -0,0 +1,13 @@ +--- +title: service start +sidebar_label: service start +slug: /service-start +--- + +Temporarily stopped services in an enclave can be restarted like so: + +```bash +kurtosis service start $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.83.1/cli-reference/service-stop.md b/docs/versioned_docs/version-0.83.1/cli-reference/service-stop.md new file mode 100644 index 0000000000..37fdfd4f5d --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/service-stop.md @@ -0,0 +1,13 @@ +--- +title: service stop +sidebar_label: service stop +slug: /service-stop +--- + +Services can be temporarily stopped in an enclave like so: + +```bash +kurtosis service stop $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.83.1/cli-reference/twitter.md b/docs/versioned_docs/version-0.83.1/cli-reference/twitter.md new file mode 100644 index 0000000000..8fab8a256a --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/cli-reference/version.md b/docs/versioned_docs/version-0.83.1/cli-reference/version.md new file mode 100644 index 0000000000..1ea3ea18dc --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/version.md @@ -0,0 +1,15 @@ +--- +title: version +sidebar_label: version +slug: /version +--- + +The `kurtosis version` command displays version information about the [CLI](./index.md). + +Example: + +```console +➜ ~ kurtosis version +CLI Version: 0.82.19 + +``` diff --git a/docs/versioned_docs/version-0.83.1/cli-reference/web.md b/docs/versioned_docs/version-0.83.1/cli-reference/web.md new file mode 100644 index 0000000000..04b037eb23 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/cli-reference/web.md @@ -0,0 +1,11 @@ +--- +title: web(beta) +sidebar_label: web(beta) +slug: /web +--- + +The following command can be used to open the Kurtosis Web UI. This feature is currently in beta. + +```bash +kurtosis web +``` diff --git a/docs/versioned_docs/version-0.83.1/code-examples.md b/docs/versioned_docs/version-0.83.1/code-examples.md new file mode 100644 index 0000000000..4dff619ede --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/code-examples.md @@ -0,0 +1,16 @@ +--- +title: Code Examples +sidebar_label: Code Examples +slug: /code-examples +--- + +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) +- [Community Supported Packages](https://github.com/kurtosis-tech/kurtosis#featured-community-packages): Kurtosis packages actively maintained by our community +- [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.83.1/concepts-reference/enclaves.md b/docs/versioned_docs/version-0.83.1/concepts-reference/enclaves.md new file mode 100644 index 0000000000..4dabe60506 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/concepts-reference/files-artifacts.md b/docs/versioned_docs/version-0.83.1/concepts-reference/files-artifacts.md new file mode 100644 index 0000000000..46037199f5 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/concepts-reference/future-references.md b/docs/versioned_docs/version-0.83.1/concepts-reference/future-references.md new file mode 100644 index 0000000000..83ada84aea --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/concepts-reference/glossary.md b/docs/versioned_docs/version-0.83.1/concepts-reference/glossary.md new file mode 100644 index 0000000000..559187ac9c --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/concepts-reference/idempotent-runs.md b/docs/versioned_docs/version-0.83.1/concepts-reference/idempotent-runs.md new file mode 100644 index 0000000000..eb70508db2 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/concepts-reference/idempotent-runs.md @@ -0,0 +1,20 @@ +--- +title: Idempotent Runs +sidebar_label: Idempotent Runs +--- + +Idempotent runs refers to Kurtosis' ability to make calls of [`kurtosis run`](../cli-reference/run.md) against an [enclave][enclaves] idempotent, meaning that the [plan](./plan.md) being submitted via `kurtosis run` is a declarative state of how the enclave should look and Kurtosis makes it so regardless of the current state of the enclave. In plain English, this means that Kurtosis will diff the plan being submitted via `kurtosis run` against what already exists in the enclave, and make only the changes necessary to get to the desired state. + + +This has several uses: + +- **Speed:** when you're running a large [Starlark](./starlark.md) script or package and a step near the end has a bug, you don't want to start over from scratch with a fresh enclave and redo all the previous steps. Idempotent runs allows you to simply fix your bug and resubmit, and Kurtosis will skip all the steps that have already been run. +- **Eternal environments:** eternal environments like shared Dev or Staging are instantiated at their start (Day 0), and then receive a constant updates into the future (Days 1+). In order for these environments to live in Kurtosis, Kurtosis needs to be able to handle Days 1+. Idempotent runs allow this, as you to simply update your Starlark script and Kurtosis updates the environment in the enclave to match. +- **GitOps:** the best DevOps companies in the world use Git to manage changes to environments: each commit updates the environment. This requires idempotency (what happens if the deploy fails for a transient reason? what happens if you need to revert a commit?). Kurtosis' idempotent runs pave the way for a native GitOps experience inside of Kurtosis itself, where the environment infrastructure-as-code is the Starlark itself. + +Kurtosis is able to do this because of its [multi-phase approach to running Starlark](./multi-phase-runs.md). Kurtosis constructs an abstract representation of the system you want before running anything (much like Terraform), so Kurtosis can compare the current state of the enclave to the desired state of the enclave and skip any unnecessary changes. + +To read in much more detail about how idempotent runs work, see [here](../explanations/how-do-idempotent-runs-work.md). + + +[enclaves]: ./enclaves.md diff --git a/docs/versioned_docs/version-0.83.1/concepts-reference/kurtosis-yml.md b/docs/versioned_docs/version-0.83.1/concepts-reference/kurtosis-yml.md new file mode 100644 index 0000000000..61a913cbc7 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/concepts-reference/locators.md b/docs/versioned_docs/version-0.83.1/concepts-reference/locators.md new file mode 100644 index 0000000000..f7aa3f0ad2 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/concepts-reference/locators.md @@ -0,0 +1,108 @@ +--- +title: Locators +sidebar_label: Locators +--- + +:::info +Locators are a part of the [Kurtosis packaging system][packages]. To read about the package system in detail, [see here][how-do-kurtosis-imports-work-explanation]. +::: + +A locator is how resources are identified when being imported in a Starlark script - namely by [`import_module`](../starlark-reference/import-module.md) and [`read_file`](../starlark-reference/read-file.md). There are two types of locators: absolute and relative. + +### Absolute Locators +Absolute locators unambiguously identify a resource using a URL-like syntax. 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. + +:::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. +::: + +### Package Restriction +Any Starlark script that wishes to use external resources must be +a part of a [Kurtosis package][packages]. + +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, 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") +``` + +### Relative Locators +Relative locators like `./helper.star` are allowed as a short alternative to the full absolute locator. However, a relative locator cannot be used to reference files outside the package. In other words, you cannot use a relative locator to reference files above the directory containing the `kurtosis.yml` file. + +Suppose we had a [Kurtosis package][packages] like so: + +``` +/ + package-repo/ + main.star + src/ + lib.star +``` + +with a `kurtosis.yml` file like so: + +```yaml +name: github.com/package-author/package-repo +``` + +The `main.star` can refer to the `lib.star` file using either relative or absolute imports: + + +```python +# valid relative import +lib_via_relative_import = import_module("./src/lib.star") + +# valid absolute import +lib_via_absolute_import = import_module("github.com/kurtosis-tech/package-repo/src/lib.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.83.1/concepts-reference/multi-phase-runs.md b/docs/versioned_docs/version-0.83.1/concepts-reference/multi-phase-runs.md new file mode 100644 index 0000000000..5da2b80a18 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/concepts-reference/packages.md b/docs/versioned_docs/version-0.83.1/concepts-reference/packages.md new file mode 100644 index 0000000000..bb282cb58c --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/concepts-reference/packages.md @@ -0,0 +1,151 @@ +--- +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 looks 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): + plan.print("Hello, world.") +``` + +:::info +More on the `plan` parameter [here][plan]. +::: + +Runnable packages can be called through the `kurtosis run` function of the CLI: + +```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`. + +### Parameterization +Kurtosis packages can accept parameters, allowing their behaviour to change. + +To make your package take in arguments, first add extra parameters to your package's `run` function: + +From this... + +```python +def run(plan): +``` + +...to this: + +```python +# Parameters without a default value are required; parameter with a default value are optional +def run(plan, some_parameter, some_other_parameter = "Default value"): +``` + +:::warning +You may come across an old style of package parameterization where the `run` function takes a single `args` variable containing all the package's parameters, like so: + +```python +# OLD STYLE - DO NOT USE +def run(plan, args): +``` + +This method is now deprecated, and will be removed in the future. +::: + +Consumers of your package can then pass in these parameters to configure your package: + + + + +```bash +kurtosis run github.com/YOUR-USER/YOUR-REPO '{"some_parameter": 5, "some_other_parameter": "New value"}' +``` +For detailed instructions on passing arguments via the CLI, see the ["Arguments" section of the `kurtosis run` documentation][kurtosis-run-arguments]. + + + + +```python +your_package = import_module("github.com/YOUR-USER/YOUR-REPO/main.star") + +def run(plan): + your_package.run(plan, some_parameter = 5, some_other_parameter = "New value") +``` + + + + + +[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 +[kurtosis-run-arguments]: ../cli-reference/run.md#arguments diff --git a/docs/versioned_docs/version-0.83.1/concepts-reference/plan.md b/docs/versioned_docs/version-0.83.1/concepts-reference/plan.md new file mode 100644 index 0000000000..c606f3a323 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/concepts-reference/plan.md @@ -0,0 +1,34 @@ +--- +title: Plan +sidebar_label: Plan +--- + +The plan is a representation of what Kurtosis will do inside 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`. + +You never construct a `Plan` object in Starlark. Instead, the `run` function of your `main.star` should have a variable called `plan`, and Kurtosis will inject the `Plan` object into it. You can then pass the object down to any functions that need it. + +For example: + +```python +# ------ main.star --------- +some_library = import_module("github.com/some-org/some-library/lib.star") + +def run(plan): + plan.print("Hello, world!") + + some_library.do_something(plan) +``` + +:::caution +Any value returned by a `Plan` function (e.g. `Plan.add_service`, `Plan.upload_files`) is a [future-reference][future-reference] to the actual value that will only exist at execution time. This means that you cannot run conditionals or manipulations on it in Starlark, at interpretation time! + +Instead, do the manipulation you need at execution time, using something like [`Plan.run_sh`][plan-run-sh] or [`Plan.run_python`][plan-run-python]. +::: + + +[future-reference]: ./future-references.md +[multi-phase-runs]: ./multi-phase-runs.md +[starlark-reference]: ./starlark.md +[plan-starlark-reference]: ../starlark-reference/plan.md +[plan-run-sh]: ../starlark-reference/plan.md#run_sh +[plan-run-python]: ../starlark-reference/plan.md#run_python diff --git a/docs/versioned_docs/version-0.83.1/concepts-reference/resource-identifier.md b/docs/versioned_docs/version-0.83.1/concepts-reference/resource-identifier.md new file mode 100644 index 0000000000..e0bd86eb48 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/concepts-reference/starlark.md b/docs/versioned_docs/version-0.83.1/concepts-reference/starlark.md new file mode 100644 index 0000000000..4a5a40c0ec --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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][packages-parameterization] +- 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 +[packages-parameterization]: ./packages.md#parameterization +[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.83.1/explanations/architecture.md b/docs/versioned_docs/version-0.83.1/explanations/architecture.md new file mode 100644 index 0000000000..933459cda7 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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. + +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.83.1/explanations/how-do-idempotent-runs-work.md b/docs/versioned_docs/version-0.83.1/explanations/how-do-idempotent-runs-work.md new file mode 100644 index 0000000000..82865bb7f1 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/explanations/how-do-idempotent-runs-work.md @@ -0,0 +1,134 @@ +--- +title: How do idempotent runs work? +sidebar_label: Idempotent Runs +--- + +Background +---------- +:::tip +To learn about what idempotent runs are in Kurtosis and the motivation behind this feature, go [here][idempotent-run-concept-reference]. +::: + +When running the `kurtosis run` command, you may notice the following message get printed: +```console +SKIPPED - This instruction has already been run in this enclave +``` +The reason this happens is because Kurtosis will optimize each run of a Starlark package based on what has already been +run in a given enclave, thus reducing execution time and resources. + +This means when you try to run the exact same package twice in a row, Kurtosis will skip all the instructions for the +second run because they were already executed in the first run. + +:::info +This feature is still experimental and can be deactivated by adding `--experimental NO_INSTRUCTIONS_CACHING` parameter +to the `kurtosis run` command. +::: + +How it works +------------ + +#### Definitions + +The __enclave plan__ is defined as the sequence of Starlark instructions that were previously executed inside a given +enclave. Meanwhile, the __submitted plan__ is defined as the set of instructions generated by interpreting the package +before it gets executed. + +When running a Starlark package in a world without idempotent runs, all the instructions are naively executed inside +the enclave and the new _post-execution enclave plan_ is set to the concatenation of the previous _enclave plan_ and +the _submitted plan_. + +To avoid re-running instructions that have already been run inside the enclave, Kurtosis will try to maximize the +overlap __between the submitted plan and the tail-end portion of the enclave plan__. In the overlapping portion, +if any, Kurtosis will re-run only the instructions that were updated. Then, if they are new instructions at the end +of the _submitted plan_ that were not in the _enclave plan_, they are executed as new instructions and added to the +_enclave plan_ + +#### Instruction equality + +To spot overlap between the _enclave plan_ and the _submitted plan_, Kurtosis needs to compare instructions one by one. +There are different level of equality: +- The submitted plan instruction is __equal__ to the enclave plan instruction - the instructions are of the same type +(i.e. two `exec`, `wait`, `upload_file` etc.) __and__ the set of arguments of the instructions are strictly identical. +- The submitted plan instruction is __an update of__ the enclave plan instruction - the instructions are of the same +type but only a subset of pre-defined arguments are identical. This only exist for a certain instructions: + - `add_service` instruction adding a service with __the same name__ but a different `ServiceConfig` object will be + considered as an update to the enclave plan instruction. The service will be restarted inside the enclave with the + new service configuration. + - `upload_file` instruction uploading a files artifact with __the same name__ but different file contents will be + considered as an update to the enclave plan instruction. The files artifact will be updated with the new contents + inside the enclave. + - `render_template` instruction creating a files artifact with _the same name_ but a different content will be + considered as an update to the enclave plan instruction. Similarly to `upload_file`, the content of the files artifact + will be updated inside the enclave. + - `store_service_file` instruction creating a files artifact with _the same name_ but either a different source path + or a different service name will be considered as an update to the enclave plan instruction. Similarly to + `upload_file`, the content of the files artifact will be updated inside the enclave. + +Two instructions that doesn't fit into any of the two categories above are considered __different__ (i.e. independent +from each other). + +It's good to callout here that a few Kurtosis instructions are __fundamentally incompatible with the concept of +idempotency__. The use of one of those instructions in the package will make the plans not resolvable, and Kurtosis will +default to the "naive" execution strategy of running the _submitted plan_ on top of the _current plan_, without even +trying the overlap them. Those instructions currently are: +- `remove_service` +- `start_service` +- `stop_service` + +#### Instruction dependencies + +Certain instructions depend on other ones, and with the concept of __instruction update__ explained above comes the +concept of __dependency between instructions__. It's easier to understand the concept with an example. + +Let's consider a submitted plan with 2 instructions: an `add_service` adding `service_1` and an `exec` on `service_1`. +If the first `add_service` instruction is considered an update when running the package, `service_1` will be updated +and therefore restarted. In that case, __even if the `exec` is equal to the matching instruction in the enclave plan__ +it will be re-run because it runs on a component (`service_1`) that has been updated. It is said that the `exec` +instruction depends on the `add_service` instruction. + +Dependency relationships can be the following: +- `add_service` instruction depends on the files artifact mounted onto the service. If one of the files artifact is +updated, the `add_service` will be re-run +- `exec` instruction depends on the service on which it runs. If the service is updated, the `exec` will be re-run. +- `request` instruction depends on the service on which it runs, similarly to `exec` +- `store_service_file`instruction depends on the service on which it runs, similarly to `exec` +- `wait` instruction depends on the service on which it runs, similarly to `exec` + +Examples +-------- + +#### Case of a _submitted plan_ being disjoint from the _enclave plan_ +No instruction get skipped, all instructions from the _submitted plan_ are executed and appended to the _enclave plan_. + +![disjoint-plans-v2.png](/img/explanations/starlark-idempotent-run/disjoint-plans-v2.png) + +#### Case of a _submitted plan_ partially overlapping the _enclave plan_ +The first two `add_service` instructions from the submitted plans are __equal__ to the last two instructions of the +enclave plan. They are therefore skipped, and only the `exec` and `store_service_files` from the submitted plan are +executed. + +![overlapping-plans-v2.png](/img/explanations/starlark-idempotent-run/overlapping-plans-v2.png) + +#### Case of a _submitted plan_ partially overlapping the _enclave plan_ with instruction updates +The `upload_file` instruction is equal, it will be skipped similarly to the case explained above. + +The `add_service` instruction from the submitted plan adding service `service_1` __is an update__ of the `add_service` +instruction from the enclave plan adding `service_1` (notice the `***` on the schema - the `ServiceConfig` object has +been updated, for example to update the container image version). It will therefore be re-run and `service_1` will +be updated inside the enclave. + +The second `add_service` instruction from the submitted plan adding service `service_2` is __equal__ to the one +from the enclave plan. It will be skipped. + +The `exec` instruction from the submitted plan is __equal__ to the one from the enclave plan. However, since +it operates on `service_1` __and__ `service_1` was updated in the submitted plan, this instruction __will also be +re-run__. + +The `store_service_file` from the submitted plan is __equal__ to the one from the enclave plan, and the service on +which it runs (`service_2`) was left intact in the submitted plan. It will therefore be skipped. + +![overlapping-plans-with-updates-v2.png](/img/explanations/starlark-idempotent-run/overlapping-plans-with-updates-v2.png) + + +[idempotent-run-concept-reference]: ../concepts-reference/idempotent-runs.md + diff --git a/docs/versioned_docs/version-0.83.1/explanations/how-do-kurtosis-imports-work.md b/docs/versioned_docs/version-0.83.1/explanations/how-do-kurtosis-imports-work.md new file mode 100644 index 0000000000..01c819391a --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/explanations/metrics-philosophy.md b/docs/versioned_docs/version-0.83.1/explanations/metrics-philosophy.md new file mode 100644 index 0000000000..0b00ed0567 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/explanations/metrics-philosophy.md @@ -0,0 +1,18 @@ +--- +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. A comprehensive list of exceptions: + - Starlark Package IDs +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.83.1/explanations/public-and-private-ips-and-ports.md b/docs/versioned_docs/version-0.83.1/explanations/public-and-private-ips-and-ports.md new file mode 100644 index 0000000000..c07f3db2e0 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/explanations/reusable-environment-definitions.md b/docs/versioned_docs/version-0.83.1/explanations/reusable-environment-definitions.md new file mode 100644 index 0000000000..ffc947fded --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/explanations/why-kurtosis-starlark.md b/docs/versioned_docs/version-0.83.1/explanations/why-kurtosis-starlark.md new file mode 100644 index 0000000000..5ea91aff58 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/explanations/why-multi-phase-runs.md b/docs/versioned_docs/version-0.83.1/explanations/why-multi-phase-runs.md new file mode 100644 index 0000000000..1243e22367 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/explanations/why-we-built-kurtosis.md b/docs/versioned_docs/version-0.83.1/explanations/why-we-built-kurtosis.md new file mode 100644 index 0000000000..eb46d857e9 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/faq.md b/docs/versioned_docs/version-0.83.1/faq.md new file mode 100644 index 0000000000..3b1cf38c9a --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/faq.md @@ -0,0 +1,8 @@ +--- +title: FAQ +sidebar_label: FAQ +slug: /faq +--- + +### Looking for our Frequently Asked Questions (FAQ) section? +Hello there! We've moved our FAQ section into [Github Discussions](https://github.com/kurtosis-tech/kurtosis/discussions/categories/q-a?discussions_q=category%3AQ%26A+) where we can engage and interact more easily with our community members. Using a forum-like approach also enables Kurtosis users to help one another more organically as well. Cheers! diff --git a/docs/versioned_docs/version-0.83.1/guides/adding-command-line-completion.md b/docs/versioned_docs/version-0.83.1/guides/adding-command-line-completion.md new file mode 100644 index 0000000000..4a28979888 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/guides/how-to-compose-your-own-testnet.md b/docs/versioned_docs/version-0.83.1/guides/how-to-compose-your-own-testnet.md new file mode 100644 index 0000000000..6855421714 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/guides/how-to-compose-your-own-testnet.md @@ -0,0 +1,191 @@ +--- +title: How to build your own private, Ethereum testnet with eth-kurtosis +sidebar_label: Build your own testnet from scratch +slug: /how-to-compose-your-own-testnet +toc_max_heading_level: 2 +--- + +:::tip +If you'd prefer to dive into the code example, visit the repository [here](https://github.com/kurtosis-tech/geth-lighthouse-package). + +If you'd prefer not to run it on your local machine, try it out on the [Kurtosis playground](https://gitpod.io/?autoStart=true&editor=code#https://github.com/kurtosis-tech/geth-lighthouse-package) +::: + +## Introduction +A testnet is an incredibly valuable tool for any web3 developer, no matter if you’re building a dApp or working on protocol-level changes. It comes as no surprise then that Ethereum has multiple public testnets in addition to a plethora of tools for local development networks (e.g. Ganache, Hardhat, Foundry Anvil). + +However, there are cases where an engineer may need to develop or test functionality that: modifies the protocol itself (execution or consensus layers), necessitates a certain scale, or interacts with another blockchain entirely (e.g. L2s/rollups, bridges, or multi-chain relayers). In these cases, a fully functioning private testnet is required - one where the user has full control over every aspect of the network and its ancillary services. + +:::note +We will review the details on when and how a full, private testnet can be useful in another article. +::: + +This guide will walk you through how to build your very own fully functioning, private Ethereum testnet using [`eth-kurtosis`](https://github.com/kurtosis-tech/eth-kurtosis/tree/main) components. In fact, the artifact you’ll end up with at the end of this tutorial will be a special type of environment definition that works at any scale you desire, is completely reproducible for CI workflows, and is modular - meaning you can add or remove other services to your network as you wish. + +**What you will do:** + +1. Create a local Kurtosis package template +2. Import required dependencies +3. Define how your private Ethereum testnet should look like. This example will leverage the Lighthouse CL client and Geth EL client to build a single, full node over Docker with [`eth-kurtosis`](https://github.com/kurtosis-tech/eth-kurtosis/tree/main). +4. Launch the private testnet locally over Docker +5. Learn about some advanced workflows you can do with `eth-kurtosis`. + +**What you will need beforehand to get started:** + +- Install [Docker & ensure its running](./installing-the-cli.md#i-install--start-docker) +- Install [Kurtosis](./installing-the-cli.md) (or [upgrade to latest](./upgrading-the-cli.md) if you already have it) +- A Github account to leverage the [template repository](https://github.com/kurtosis-tech/package-template-repo) + +### 1. Set up an empty Kurtosis package +To begin, create and `cd` into a directory to hold your files: +```bash +mkdir my-testnet && cd my-testnet +``` +Next, create a file called `network_params.json` in that folder with the following contents: +```json +{ + "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": 10, + "capella_fork_epoch": 2, + "deneb_fork_epoch": 500 +} +``` +The contents above will be used to define the specific parameters with which to start the network with. + +Now, create a `kurtosis.yml` file in the same folder with the following: +```yml +name: github.com/foo-bar/my-testnet +``` +Awesome. You have just created the beginnings of your first [Kurtosis package](../concepts-reference/packages.md)! This package will form the backbone of the environment definition you will use to instantiate and deploy your private testnet. A Kurtosis package is completely reproducible, modular, and will work locally (Docker, Minikube, k3s, etc) or in the cloud, on backends like EC2 or Kubernetes. + +### 2. Import dependencies +Now that you have a local project to house your definition and some parameters to start the network with, its time to actually build the network. First, create a Starlark file called `main.star` and add the following three lines: +```python +# main.star +geth = import_module("github.com/kurtosis-tech/geth-package/lib/geth.star") +lighthouse = import_module("github.com/kurtosis-tech/lighthouse-package/lib/lighthouse.star") +network_params = json.decode(read_file("./network_params.json")) +``` + +In the first two lines, you're using [Locators](../concepts-reference/locators.md) to import in `geth.star` and `lighthouse.star` files from Github, making them available to use in your testnet definition. These files themselves are environment definitions that can be used to bootstrap and start up a Geth execution layer client and a Lighthouse consensus layer client as part of your testnet - which is exactly what you will do next. + +:::note +Feel free to check out the [`geth.star`](https://github.com/kurtosis-tech/geth-package/blob/main/lib/geth.star) and [`lighthouse.star`](https://github.com/kurtosis-tech/lighthouse-package/blob/main/lib/lighthouse.star) to understand how they work. At a high level, the definition instructs Kurtosis to generate genesis data, set up pre-funded accounts, and then launches the client using the client container images. +::: + +Finally, we are converting the local `network_params.json` file into a format that can be used in your environment definition using [`json.decode()`](https://bazel.build/rules/lib/core/json#decode) and [`read_file()`](../starlark-reference/read-file.md). + +### 3. Define how your testnet gets built +Now that you have all the necessary dependencies, you can start writing the function that will instantiate the network. Within your `main.star` file, add the following 3 new lines: + +```python +def run(plan): + final_genesis_timestamp = geth.generate_genesis_timestamp() + el_genesis_data = geth.generate_el_genesis_data(plan, final_genesis_timestamp, network_params) +``` + +What you've just done here is define a function using `run(plan)` to house all of the methods you will use for instantiating the network. Within this method, you will call the [`generate_genesis_timestamp()` function](https://github.com/kurtosis-tech/geth-package/blob/main/lib/geth.star#L58), from the `geth.star` you imported earlier, to generate an abitrary timestamp for the genesis of your network. This is important for time-based forks that you may want to use later on. Next, you will generate some genesis data for the execution layer using [`generate_el_genesis_data`](https://github.com/kurtosis-tech/geth-package/blob/main/lib/geth.star#L43) which was imported from `geth.star` as well. Under the hood, the genesis data is being generated using the Ethereum Foundation's [`ethereum-genesis-generator`](https://github.com/ethpandaops/ethereum-genesis-generator). + +You can already see the benefit of composable environment definitions: you don't need to deal with nor understand how the genesis data is being generated. You can rely on the framework built and used by the Ethereum Foundation for your testnet's genesis data. + +With some execution layer genesis data in hand, you will now bootstrap the node! Go ahead and add the next 3 lines to your `main.star` file inside the same `def run(plan)` function so that your final result looks like: + +```python +# main.star +geth = import_module("github.com/kurtosis-tech/geth-package/lib/geth.star") +lighthouse = import_module("github.com/kurtosis-tech/lighthouse-package/lib/lighthouse.star") +network_params = json.decode(read_file("./network_params.json")) + +def run(plan): + # Generate genesis, note EL and the CL needs the same timestamp to ensure that timestamp based forking works + final_genesis_timestamp = geth.generate_genesis_timestamp() + el_genesis_data = geth.generate_el_genesis_data(plan, final_genesis_timestamp, network_params) + + # NEW LINES TO ADD: + # Run the nodes + el_context = geth.run(plan, network_params, el_genesis_data) + lighthouse.run(plan, network_params, el_genesis_data, final_genesis_timestamp, el_context) + + return +``` + +Here, the Geth client is launched using the `run()` function in `geth.star` and then returns all the relevant information about the client to `el_context`, including the [Ethereum Node Record](https://github.com/sigp/enr). This information, alongside the network parameters, genesis data, and the genesis timestamp, are then passed in as arguments in the next command: `lighthouse.run()` which bootstraps the Lighthouse consensus layer client. + +And that is it! In these short few lines, you now have an environment definition that spins up a full stacking Ethereum node with Geth and Lighthouse over Docker on your local machine. + +### 4. Run your new testnet! +Finally, time to give it a spin! Go back to your terminal and from within the `my-testnet` directory, run: +``` +kurtosis run . +``` + +Kurtosis will interpret the environment definition you just wrote, validate that everything will work, and then execute the instructions to instantiate your Ethereum node inside an [enclave](../concepts-reference/enclaves.md), which is just a sandbox environment that will house your node. Kurtosis will handle the importing of the `lighthouse.star` and `geth.star` files from Github. The output you'll get at the end should look like this: + +```bash +Starlark code successfully run. No output was returned. +INFO[2023-08-04T16:07:28+02:00] ========================================================== +INFO[2023-08-04T16:07:28+02:00] || Created enclave: tranquil-woodland || +INFO[2023-08-04T16:07:28+02:00] ========================================================== +Name: tranquil-woodland +UUID: ac3877184757 +Status: RUNNING +Creation Time: Fri, 04 Aug 2023 16:06:57 CEST + +========================================= Files Artifacts ========================================= +UUID Name +8a1de99b7224 1-lighthouse-eth-0-63 +271f6e53a7e1 cl-genesis-data +6c116cfcc7d1 el-genesis-data +7549ddc4135a genesis-generation-config-cl +d266370395ef genesis-generation-config-el +d204de12687e geth-prefunded-keys +a069f55dc147 prysm-password + +========================================== User Services ========================================== +UUID Name Ports Status +cb04101e98fd cl-client-0 http: 4000/tcp -> http://127.0.0.1:50646 RUNNING + metrics: 5054/tcp -> http://127.0.0.1:50647 + tcp-discovery: 9000/tcp -> 127.0.0.1:50648 + udp-discovery: 9000/udp -> 127.0.0.1:59240 +f377be0f55f8 cl-client-0-validator http: 5042/tcp -> 127.0.0.1:50649 RUNNING + metrics: 5064/tcp -> http://127.0.0.1:50650 +19b325f68893 el-client-0 engine-rpc: 8551/tcp -> 127.0.0.1:50639 RUNNING + rpc: 8545/tcp -> 127.0.0.1:50641 + tcp-discovery: 30303/tcp -> 127.0.0.1:50640 + udp-discovery: 30303/udp -> 127.0.0.1:49442 + ws: 8546/tcp -> 127.0.0.1:50642 +a9608eaf4942 prelaunch-data-generator-cl-genesis-data RUNNING +a1e33f5b7141 prelaunch-data-generator-cl-validator-keystore STOPPED +971aaffb412d prelaunch-data-generator-el-genesis-data RUNNING +``` + +You'll now see in the `User Services` section all the ports that you will use to connect to and interact with your local node, including the RPC URL. Your port numbers may differ from the one above. + +Congratulations! You now have a full Ethereum staking node for all your private testnet needs. + +### 5. Advanced Workflows +You may already know what you want to do with the private testnet you've just spun up, and that's great! We hope this was helpful in getting you started and to show you just how easy it was to write your own testnet definition using Kurtosis. + +Otherwise, we've got some neat ideas for what you can do next. If you need a hand with any of the below, feel free to let us know in our [Github Discussions](https://github.com/kurtosis-tech/kurtosis/discussions/new/choose) where we and members of our community can help! +* Deploy your node in a Kubernetes cluster for collaborative work and scale it out to multiple nodes! Check out our docs for how to do so [here](https://docs.kurtosis.com/k8s/). +* Simulate MEV workflows by importing the [MEV Package](https://github.com/kurtosis-tech/mev-package) into your testnet definition. The MEV package deploys and configures the Flashbots suite of products to your local Ethereum testnet and includes: MEV-Boost, MEV-Flood, and MEV-relay, and any required dependencies (postgres & redis). Here's a full example of this set up [here](https://github.com/kurtosis-tech/geth-lighthouse-mev-package). +* Connect other infrastructure (oracles, relayers, etc) to the network by adding more to your `main.star` file! Remember, this is an environment definition and you can import any pre-existing packages that you may find useful. Here are a [few examples](https://github.com/kurtosis-tech/awesome-kurtosis/tree/main) +* Deploy your dApp onto the local network! Hardhat can be used to do so by using the given RPC URL & the `network_id` defined in the `network_params.json` you wrote at the beginning. In your case, the `network_id` should be: `3151908`. A more thorough example of this workflow can also be found [here](./how-to-local-eth-testnet.md). + +We're currently building out more components of [`eth-kurtosis`](https://github.com/kurtosis-tech/eth-kurtosis/tree/main), which serves as an index of plug-and-play components for Ethereum private testnets. We're building support for more clients - so let us know if there's something you would love to see added to the index! + +### Conclusion + +To recap, in this guide you: +* Created a working directory locally for your Kurtosis package +* Wrote a very short environment definition, `main.star`, which imported the client launchers for your node, generated the necessary starting state, and then launched them! + +You also saw first-hand how the composability aspect of Kurtosis environment definitions were used to abstract away a lot of the complexities that come with bootstrapping your own node. And because this is entirely reproducible, your team can use this as a private blockchain for validating and testing changes for your application. + +We hope this guide was helpful and 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`](../cli-reference/feedback.md) from the CLI to file an issue in our [Github](https://github.com/kurtosis-tech/eth-kurtosis/issues) or post your question in our [Github Discussions](https://github.com/kurtosis-tech/kurtosis/discussions). + +Thank you! diff --git a/docs/versioned_docs/version-0.83.1/guides/how-to-full-mev-with-eth2-package.md b/docs/versioned_docs/version-0.83.1/guides/how-to-full-mev-with-eth2-package.md new file mode 100644 index 0000000000..9aabe117af --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/guides/how-to-full-mev-with-eth2-package.md @@ -0,0 +1,213 @@ +--- +title: How to launch a private Ethereum testnet with Flashbot's MEV Boost implementation of Proposer Builder Seperation (PBS) +sidebar_label: Launch a testnet with MEV infra +slug: /how-to-full-mev-with-eth2-package +toc_max_heading_level: 2 +--- + +:::tip +Here are some quick short-cuts for folks who would prefer: +* To get going right away: install Kurtosis & Docker and then run: `kurtosis run github.com/kurtosis-tech/eth2-package '{"mev_type": "full"}'` +* To dive into the code example: visit the repository [here](https://github.com/kurtosis-tech/eth2-package). +* Not to run this package on their local machine: try it out on the [Kurtosis playground](https://gitpod.io/?autoStart=true&editor=code#https://github.com/kurtosis-tech/eth2-package) +::: + +We're elated to share that the [`eth2-package`](https://github.com/kurtosis-tech/eth2-package) now supports the Flashbot's implementation of [Proposer-Builder Separation (PBS)](https://ethereum.org/en/roadmap/pbs/) using [MEV-Boost](https://boost.flashbots.net) protocol. + +This milestone marks a huge step forward in the journey towards a full, in-protocol PBS implementation for Proof-of-Stake Ethereum as developers across the ecosystem now have a way to instantiate fully functioning testnets to validate functionality, behvaior, and scales across all client combinations with a Builder API implementation (Flashbots', in this case). + +Keep reading to learn [how it all works](#brief-overview-of-the-architecture) & [how to get started with the `eth2-package`](#quickstart). + +#### Why `eth2-package`? +As a reminder, the [`eth2-package`](https://github.com/kurtosis-tech/eth2-package) is a reproducible and portable environment definition that should be used to bootstrap & deploy private testnets. The package will function the exact same way locally or in the cloud over Docker or Kubernetes, supports all major Execution Layer (EL) and Consensus Layer (CL) client implementations, and can be scaled to whatever size your team needs - limited only by your underlying hardware/backend. + +#### What if I only want the MEV parts? +And if that wasn't enough, Kurtosis environment definitions (known as [Packages](https://docs.kurtosis.com/concepts-reference/packages/)) are entirely composable, meaning you can define and build-your-own private testnet using only the parts you need and with the option of adding your own services (e.g. MEV searcher tools). Feel free to check out the following [code example](https://github.com/kurtosis-tech/2-el-cl-mev-package/blob/main/main.star). + +## Brief overview of the architecture +Explicitly, the [`eth2-package`](https://github.com/kurtosis-tech/eth2-package) supports two modes: `full-mev` and `mock-mev`. + +The former mode is valuable for validating behavior between the protocol and out-of-protocol middle-ware infrastructure (e.g. searchers, relayer) and instantiates [`mev-boost`](https://github.com/flashbots/mev-boost), [`mev-relay`](https://github.com/flashbots/mev-boost-relay), [`mev-flood`](https://github.com/flashbots/mev-flood) and Flashbot's Geth-based block builder called [`mev-builder`](https://github.com/flashbots/builder). The latter mode will only spin up [`mev-boost`](https://github.com/flashbots/mev-boost) and a [`mock-builder`](https://github.com/marioevz/mock-builder), which is useful for testing in-protocol behavior like testing if clients are able to call the relayer for a payload via `mev-boost`, reject invalid payloads, or trigger the [circuit breaker](https://hackmd.io/@ralexstokes/BJn9N6Thc) to ensure functionality of the beacon chain. + +The `eth2-package` with MEV emulation are already in use by client teams to help uncover bugs (examples [here](https://github.com/prysmaticlabs/prysm/pull/12736) and [here](https://github.com/NethermindEth/nethermind/commit/4d805769159dc0717aa1ba38cc3ebc53f9a375cf)). + +Everything you see below in the architecture diagram gets configured, initialized, and bootstrapped together by Kurtosis. + +![mev-arch](/img/guides/full-mev-infra-arch-diagram.png) + +#### Caveats: +* The `mev-boost-relay` service requires Capella at an epoch of non-zero. For the eth2-package, the Capella fork is set to happen after the first epoch to be started up and fully connected to the CL client. +* Validators (64 per node by default, so 128 in the example in this guide) will get registered with the relay automatically after the 2nd epoch. This registration process is simply a configuration addition to the mev-boost config - which Kurtosis will automatically take care of as part of the set up. This means that the `mev-relay` infrastructure only becomes aware of the existence of the validators after the 2nd epoch. +* After the 3rd epoch, the `mev-relay` service will begin to receive execution payloads (`eth_sendPayload`, which does not contain transaction content) from the `mev-builder` service (or `mock-builder` in `mock-mev` mode). +* Validators will then start to receive validated execution payload headers from the `mev-relay` service (via `mev-boost`) after the 4th epoch. The validator selects the most valuable header, signs the payload, and returns the signed header to the relay - effectively proposing the payload of transactions to be included in the soon-to-be-proposed block. Once the relay verifies the block proposer's signature, the relay will respond with the full execution payload body (incl. the transaction contents) for the validator to use when proposing a `SignedBeaconBlock` to the network. +* You may notice in the `mev-flood` logs that there may be transactions that fail to get processed by the node(s) in your devnet with the following errors: `Error: replacement fee too low [ See: https://links.ethers.org/v5-errors-REPLACEMENT_UNDERPRICED ]`. Don't be alarmed: this can happen when transactions are sent too quickly to the network, resulting in the node receiving transactions with the same nonce. When this happens, the node rejects the transactions becauase the node assumes you're trying to replace the old pending transaction with a new one. You can change the frequency using `mev-flood`'s `--secondsPerBundle (-p )` flag in the [`spam` command](https://github.com/flashbots/mev-flood#send-swaps). + +:::note +Quick aside on what `mev-flood` does: +Once the network is online, `mev-flood` will deploy UniV2 smart contracts, provision liquidity on UniV2 pairs, & begin to send a constant stream of UniV2 swap transactions to the network's public mempool. Depending on the mode you're running, either the `mock-builder` or Flashbot's `mev-builder`, the transactions will be bundled into payloads for downstream use by the relayer or by validators themselves. It is important to note that `mev-flood` will only be initialized with the `full-mev` set up and will send transactions with a non-zero block value. Read more about [`mev-flood` here](https://github.com/flashbots/mev-flood). +::: + +## Quickstart +Leveraging the [`eth2-package`](https://github.com/kurtosis-tech/eth2-package) is simple. In this short quickstart, you will: +1. Install Docker & Kurtosis locally. +2. Configure your network using a `.json` file. +3. Run a single command to launch your network with `full MEV`. +4. Visit the website to witness payloads being delivered from the Relayer to the `mev-boost` sidecar connected to each validator (for block proposals). + +#### Install dependencies +* [Install Docker](https://docs.docker.com/get-docker/) and ensure the Docker Daemon is running on your machine (e.g. open Docker Desktop). You can quickly check if Docker is running by running: `docker image ls` from your terminal to see all your Docker images. +* [Install Kurtosis](https://docs.kurtosis.com/install/#ii-install-the-cli) or [upgrade Kurtosis to the latest version](https://docs.kurtosis.com/upgrade). You can check if Kurtosis is running using the command: `kurtosis version`, which will print your current Kurtosis engine version and CLI version. + +#### Configure your network +Next, create a file titled: `eth2-package-params.json` in your working directory and populate it with: +```json +{ + "participants": [{ + "el_client_type": "geth", + "el_client_image": "ethereum/client-go:latest", + "el_client_log_level": "", + "el_extra_params": [], + "cl_client_type": "lighthouse", + "cl_client_image": "sigp/lighthouse:latest", + "cl_client_log_level": "", + "beacon_extra_params": [], + "validator_extra_params": [], + "builder_network_params": null + }], + "network_params": { + "network_id": "3151908", + "deposit_contract_address": "0x4242424242424242424242424242424242424242", + "seconds_per_slot": 12, + "slots_per_epoch": 32, + "num_validator_keys_per_node": 64, + "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", + "deneb_for_epoch": 500 + }, + "verifications_epoch_limit": 5, + "global_client_log_level": "info", + "mev_type": "full" +} +``` +You will use the above file by passing it in at runtime, effectively enabling you to define the way your network should look using parameters. + +#### Launch the network with `full MEV` +Great! You're now ready to bring up your own network. Simply run: +```bash +kurtosis run --enclave eth-network github.com/kurtosis-tech/eth2-package "$(cat ~/eth2-package-params.json)" +``` +Kurtosis will then begin to spin up your private Ethereum testnet with `full MEV`. You will see a stream of text get printed in your terminal as Kurtosis begins to generate genesis files, configure the Ethereum nodes, launch a Grafana and Prometheus instance, and bootstrap the network together with the full suite of MEV products from Flashbots. In ~2 minutes, you should see the following output at the end: +```bash +Starlark code successfully run. Output was: +{ + "grafana_info": { + "dashboard_path": "/d/QdTOwy-nz/eth2-merge-kurtosis-module-dashboard?orgId=1", + "password": "admin", + "user": "admin" + } +} + +INFO[2023-08-03T11:16:00+02:00] ==================================================== +INFO[2023-08-03T11:16:00+02:00] || Created enclave: eth-network || +INFO[2023-08-03T11:16:00+02:00] ==================================================== +Name: eth-network +UUID: 1d467f353496 +Status: RUNNING +Creation Time: Thu, 03 Aug 2023 11:06:50 CEST + +========================================= Files Artifacts ========================================= +UUID Name +004cb2a16def 1-lighthouse-geth-0-63 +e98eee4d8a99 2-lighthouse-geth-64-127 +601b49f6e437 cl-forkmon-config +21192db4c9b4 cl-genesis-data +fcdd39be227b el-forkmon-config +38905cf9e831 el-genesis-data +0ba35b186c20 genesis-generation-config-cl +b477313c48f4 genesis-generation-config-el +b119fb95bd44 geth-prefunded-keys +c4fd103c5447 grafana-config +122cfb453ebe grafana-dashboards +b86556fccf74 prometheus-config +2d2d99849ff0 prysm-password + +========================================== User Services ========================================== +UUID Name Ports Status +1bde5712f965 cl-1-lighthouse-geth http: 4000/tcp -> http://127.0.0.1:62873 RUNNING + metrics: 5054/tcp -> http://127.0.0.1:62874 + tcp-discovery: 9000/tcp -> 127.0.0.1:62875 + udp-discovery: 9000/udp -> 127.0.0.1:53993 +57f94044300c cl-1-lighthouse-geth-validator http: 5042/tcp -> 127.0.0.1:62876 RUNNING + metrics: 5064/tcp -> http://127.0.0.1:62877 +ae2d5b824656 cl-2-lighthouse-geth http: 4000/tcp -> http://127.0.0.1:62879 RUNNING + metrics: 5054/tcp -> http://127.0.0.1:62880 + tcp-discovery: 9000/tcp -> 127.0.0.1:62878 + udp-discovery: 9000/udp -> 127.0.0.1:65058 +c1eb34a91b7e cl-2-lighthouse-geth-validator http: 5042/tcp -> 127.0.0.1:62882 RUNNING + metrics: 5064/tcp -> http://127.0.0.1:62881 +65e1ae6652c9 cl-forkmon http: 80/tcp -> http://127.0.0.1:62933 RUNNING +e7f673086384 el-1-geth-lighthouse engine-rpc: 8551/tcp -> 127.0.0.1:62861 RUNNING + rpc: 8545/tcp -> 127.0.0.1:62863 + tcp-discovery: 30303/tcp -> 127.0.0.1:62862 + udp-discovery: 30303/udp -> 127.0.0.1:56858 + ws: 8546/tcp -> 127.0.0.1:62860 +3048d9aafc12 el-2-geth-lighthouse engine-rpc: 8551/tcp -> 127.0.0.1:62866 RUNNING + rpc: 8545/tcp -> 127.0.0.1:62864 + tcp-discovery: 30303/tcp -> 127.0.0.1:62867 + udp-discovery: 30303/udp -> 127.0.0.1:62287 + ws: 8546/tcp -> 127.0.0.1:62865 +70e19424c664 el-forkmon http: 8080/tcp -> http://127.0.0.1:62934 RUNNING +f4bebfdc819b grafana http: 3000/tcp -> http://127.0.0.1:62937 RUNNING +219954ae8f7e mev-boost-0 api: 18550/tcp -> 127.0.0.1:62931 RUNNING +287c555090c6 mev-boost-1 api: 18550/tcp -> 127.0.0.1:62932 RUNNING +2fedae36a1f8 mev-flood RUNNING +bb163cad3912 mev-relay-api api: 9062/tcp -> 127.0.0.1:62929 RUNNING +5591d1d17ec5 mev-relay-housekeeper RUNNING +026f3744c98f mev-relay-website api: 9060/tcp -> 127.0.0.1:62930 RUNNING +096fdfb33909 postgres postgresql: 5432/tcp -> postgresql://127.0.0.1:62928 RUNNING +f283002d8c77 prelaunch-data-generator-cl-genesis-data RUNNING +af010cabc0ce prelaunch-data-generator-el-genesis-data RUNNING +3fcd033e1d38 prometheus http: 9090/tcp -> http://127.0.0.1:62936 RUNNING +145b673410f9 redis client: 6379/tcp -> 127.0.0.1:62927 RUNNING +2172a3e173f8 testnet-verifier RUNNING +f833b940ae5b transaction-spammer RUNNING +``` + +As you can see above, there is *a lot* going on in your enclave - but don't worry, let's go through everything together. + +The first section that gets printed contains some basic metadata about the enclave that was spun up. This includes the name of the enclave `eth-network`, its [Resource Idenfitier](https://docs.kurtosis.com/concepts-reference/resource-identifier/), your enclave's status, and the time it was created. + +Next, you'll see a section dedicated to [Files Artifacts](https://docs.kurtosis.com/concepts-reference/files-artifacts/), which are Kurtosis' first-class representation of data inside your enclave, stored as compressed TGZ files. You'll notice there are configuration files for the nodes, grafana, and prometheus as well as private keys for pre-funded accounts and genesis-related data. These files artifacts were generated and used by Kurtosis to start the network and abstracts away the complexities and overhead that come with generating validator keys and getting genesis and node config files produced and mounted to the right containers yourself. + +Lastly, there is a section called `User Services` which display the number of services (running in Docker containers) that make up your network. You will notice that there are 2 Ethereum nodes, each with a `MEV-Boost` instance spun up & connected to it. In addition to this, you will see the rest of the Flashbots MEV infrastructure including the `mev-relay` suite of services (read more about the `mev-relay` services [here](https://github.com/flashbots/mev-boost-relay/blob/main/ARCHITECTURE.md)) and `mev-flood`. By default, the `eth2-package` also comes with supporting services which include a fork monitor, redis, postgres, grafana, prometheus, a transaction spammer, a testnet-verifier, and the services used to generate genesis data. Both of the Redis and Postgres instances are required for `mev-relay` to function properly.Each of these services are running in Docker containers inside your local enclave & Kurtosis has automatically mapped each container port to your machine's ephemeral ports for seamless interaction with the services running in your enclave. + +#### Visit the website to see registered validators and delivered payloads +Now that your network is online, you can visit the relay website using the local port mapped to that endpoint. For this example, it will be `127.0.0.1:62930`, but it will be different for you. + +![flashbots-website](/img/guides/full-mev-flashbots-website.png) + +The screenshot above is what the website looks like after the 4th epoch. You can see that all 128 validators (2 nodes, each with 64 validators) are registered. The table below will display recently delivered and verified payloads from `mev-relay` to the `mev-boost` sidecar on each node. + +And there you have it! You've now spun up a private Ethereum testnet over Docker with the Flashbot's implementation of PBS! + +## Roadmap +The inclusion of a Proposer Builder Seperation (PBS) implemention was in support of the Ethereum Foundation's efforts to validate functionality and behavior in end-to-end testing (between in-protocol and out-of-protocol infrastructure), as well as the functionality of the beacon chain for in-protocol code paths (e.g. can clients: call for payloads reject invalid payloads, and trigger the circuit breaker when necessary). + +The next immediate thing we hope to do is to *decompose* the environment definition into smaller pieces, enabling developers to build-their-own MEV-enabled systems by simply importing only the parts of the MEV infrastructure that they need. We've begun working on this already with [eth-kurtosis](https://github.com/kurtosis-tech/eth-kurtosis), which contains an index of composable building blocks to define your own testnet. + +If there are other use cases you had in mind (e.g. fuzzing the network at the protocol level) or have questions about `eth-kurtosis` or this `eth2-package`, please don't hesitate to reach out! + +## Conclusion +This guide was meant to be quick - we hope it was. To recap, you: +- Installed Kurtosis and Docker +- Created a `.json` file that contains the necessary parameters for the network +- Ran a single command to spin up a private Ethereum testnet with MEV infrastructure + +The `eth2-package` is available for anyone to use, will work the same way on your local machine or in the cloud, and will run on Docker or Kubernetes. + +You saw first-hand how packages, effectively environment definitions, are written once and then can be used by anyone in a very trivial way to reproduce the environment. This accelerates developer velocity by enabling engineers to spend less time on configuring and setting up development and testing frameworks, and more time instead on building the unique features and capabilities for their projects. + +Additionally, we hope you also enjoyed the parameterizability aspect of Kurtosis Packages. By changing the `eth2-package-params.json`, you can get a fine-tune your testnet however you see fit. + +We hope this guide was helpful and 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`](../cli-reference/feedback.md) from the CLI to file an issue in our [Github](https://github.com/kurtosis-tech/eth-kurtosis/issues) or post your question in our [Github Discussions](https://github.com/kurtosis-tech/kurtosis/discussions). + +Thank you! diff --git a/docs/versioned_docs/version-0.83.1/guides/how-to-local-eth-testnet.md b/docs/versioned_docs/version-0.83.1/guides/how-to-local-eth-testnet.md new file mode 100644 index 0000000000..d10777c52f --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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 + +With 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.83.1/guides/how-to-parameterize-cassandra.md b/docs/versioned_docs/version-0.83.1/guides/how-to-parameterize-cassandra.md new file mode 100644 index 0000000000..02aff80654 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/guides/how-to-parameterize-cassandra.md @@ -0,0 +1,396 @@ +--- +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. + +### 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 +[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.83.1/guides/installing-historical-versions.md b/docs/versioned_docs/version-0.83.1/guides/installing-historical-versions.md new file mode 100644 index 0000000000..cad90a5ff3 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/guides/installing-historical-versions.md @@ -0,0 +1,102 @@ +--- +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. + + + + + +:::tip +In order to upgrade Kurtosis to another version *after you've performed a downgrade (i.e. installed a historical version)*, you must first uninstall the version of Kurtosis you've installed and re-install Kurtosis. When using Homebrew, the workflow will be (replacing `HISTORICAL-VERSION` with the historical version you have installed): +1. `brew uninstall brew uninstall kurtosis-tech/tap/kurtosis-cli@HISTORICAL-VERSION` +2. `brew install kurtosis-tech/tap/kurtosis-cli` for upgrading to the latest version or `brew install kurtosis-tech/tap/kurtosis-cli@TARGET-VERSION` for upgrading to a specific version +3. `kurtosis engine restart` +::: + + +[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.83.1/guides/installing-the-cli.md b/docs/versioned_docs/version-0.83.1/guides/installing-the-cli.md new file mode 100644 index 0000000000..6345dd96ef --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/guides/installing-the-cli.md @@ -0,0 +1,120 @@ +--- +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. + +:::info +We're working on a cloud-hosted version of Kurtosis that doesn't require installing anything. If this interests you, let us know [here](https://mp2k8nqxxgj.typeform.com/to/U1HcXT1H) and we'll let you know when it's ready! +::: + +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.83.1/guides/running-in-ci.md b/docs/versioned_docs/version-0.83.1/guides/running-in-ci.md new file mode 100644 index 0000000000..33fb592fc4 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/guides/running-in-k8s.md b/docs/versioned_docs/version-0.83.1/guides/running-in-k8s.md new file mode 100644 index 0000000000..25582bebf0 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/guides/running-in-k8s.md @@ -0,0 +1,96 @@ +--- +title: Running Kurtosis in Kubernetes +sidebar_label: Running in Kubernetes +slug: /k8s +--- + +This guide assumes that you have [Kurtosis installed](./installing-the-cli.md). + +If you would like more information on Kubernetes and how to set up, run and manage a cluster check out these offical [docs](https://kubernetes.io/docs/home/). + +Please note that in order to ensure Kurtosis works the same way over Kubernetes as it does over Docker locally, service names must be a valid [RFC-1035 Label Name](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#rfc-1035-label-names). This means service names must contain: at most 63 characters, only lowercase alphanumeric characters or '-', start with an alphabetic character, and end with an alphanumeric character. + +I. Create a Kubernetes Cluster +----------------- + +There are many diferent ways to get a Kubernetes cluster (roughly ordered easiest to hardest): + +- Use [Kubernetes provided with Docker Desktop](https://docs.docker.com/desktop/kubernetes/) +- Install [Minikube](https://github.com/kubernetes/minikube) +- Use [k3s](https://k3s.io/) +- Deploy it on an onprem cluster and manage the machine provisioning yourself +- Deploy it on the cloud, managing the Kubernetes nodes on cloud instances yourself (e.g. EC2, AVM, GCE, etc) +- 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: + +- 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/). +- 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//Library/Application Support/kurtosis/kurtosis-config.yml` on MacOS. +2. 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` +::: + + +V. \[Optional] Activate the enclave pool to accelerate the enclave creation time +-------------------------------- + +This step is optional, but we recommend taking it as it improves the user experience during the enclave creation, specifically regarding speed. + +Creating a new enclave from scratch demands several time-consuming engine tasks and the creation of resources. + +The enclave pool feature was introduced to reduce the time it takes for a user to run a Kurtosis package in the cloud by spinning up the enclaves before they are needed. + +The enclave pool is a functionality of the Kurtosis engine that automatically creates `idle` enclaves, when the engine is started, that are then used whenever users need to create a new enclave (e.g: when running the `kurtosis enclave add` command). + +This mechanism reduces enclave creation time by using a running `idle` enclave when a new enclave is requested from the engine. + +To enable this feature you have to run the following: + +1. Run `kurtosis engine restart --enclave-pool-size {pool-size-number}`. If you already follow the previous step and replace the {pool-size-number} with an integer + +OR + +1. Run `kurtosis engine start --enclave-pool-size {pool-size-number}`. If the engine has not been started yet. diff --git a/docs/versioned_docs/version-0.83.1/guides/running-in-kurtosis-cloud.md b/docs/versioned_docs/version-0.83.1/guides/running-in-kurtosis-cloud.md new file mode 100644 index 0000000000..5485abfe73 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/guides/running-in-kurtosis-cloud.md @@ -0,0 +1,40 @@ +--- +title: Running Kurtosis in Kurtosis Cloud +sidebar_label: Running in Kurtosis Cloud +slug: /cloud +--- + +Kurtosis Cloud is a fully managed cloud offering and accompanying self-service workflows for a stress-free, easy way to deploy test and dev environments, that live as long as you need them to, directly onto remote infrastructure. By logging into our [cloud portal](https://cloud.kurtosis.com), a cloud instance will be provisioned to run your test and dev enclaves. + +You can interact with your enclaves using the UI (or the [CLI](./installing-the-cli.md#ii-install-the-cli) for more advanced use cases). + +![enclave-manager-ui](/img/guides/enclave-manager-ui.png) + +A Kurtosis cloud instance is an AWS EC2 instance running the Kurtosis engine, the Kurtosis API controller and your enclave services inside Docker. The service ports are forwarded to your local machine. + +![cloud-arch](/img/guides/cloud-arch.png) + +### Advantages of running Kurtosis enclaves in Kurtosis Cloud + +In addition to offloading the compute to a cloud infrastructure, Kurtosis Cloud comes with other advantages. +When provisioning a cloud instance, Kurtosis will create a specific AWS user account and a storage space in S3. + +Services running inside a Kurtosis enclave in Kurtosis Cloud can freely read and write objects from/to this S3 storage. + +:::warning S3 storage is publicly accessible +While only the owner of the S3 storage is permitted to write to the S3 storage, the data is publicly accessible to +anyone that knows the object key. For this reason, we don't recommend storing sensitive data in the S3 storage. +::: + +The AWS user key as well as the information on the user S3 space is provided to all Starlark packages running in the +cloud via the global `kurtosis` module. The following variables are available inside Starlark and can be passed as +environment variables or simple arguments to the services started inside the enclave: +- `kurtosis.aws_access_key_id` and `kurtosis.aws_secret_access_key`: The AWS user key pair required to authenticate to +AWS +- `kurtosis.aws_bucket_region`, `kurtosis.aws_bucket_name` and `kurtosis.aws_bucket_user_folder`: The bucket region and +name, as well as the specific user folder the AWS user is authorized to access. + +:::tip AWS user permissions +The AWS user created has a very restricted set of permissions by default. It can only read and write to its user folder +inside the S3 bucket. But it is possible to request more access, reach out to us via Discord or by email. +::: diff --git a/docs/versioned_docs/version-0.83.1/guides/upgrading-the-cli.md b/docs/versioned_docs/version-0.83.1/guides/upgrading-the-cli.md new file mode 100644 index 0000000000..c4bed56505 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/guides/upgrading-the-cli.md @@ -0,0 +1,95 @@ +--- +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 +``` + +:::tip +In order to upgrade Kurtosis to another version *after you've performed a downgrade (i.e. installed a historical version)*, you must first uninstall the version of Kurtosis you've installed and re-install Kurtosis. When using Homebrew, the workflow will be (replacing `HISTORICAL-VERSION` with the historical version you have installed): +1. `brew uninstall brew uninstall kurtosis-tech/tap/kurtosis-cli@HISTORICAL-VERSION` +2. `brew install kurtosis-tech/tap/kurtosis-cli` for upgrading to the latest version or `brew install kurtosis-tech/tap/kurtosis-cli@TARGET-VERSION` for upgrading to a specific version +3. `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.83.1/home.md b/docs/versioned_docs/version-0.83.1/home.md new file mode 100644 index 0000000000..6701727eb8 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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 about 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.83.1/quickstart.md b/docs/versioned_docs/version-0.83.1/quickstart.md new file mode 100644 index 0000000000..b31849f68c --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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 takes ~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 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): + +```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 its 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 this approach 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, create a file called `kurtosis.yml` next to your `main.star file` (in your working directory, `kurtosis-quickstart`) 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 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.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.83.1/roadmap.md b/docs/versioned_docs/version-0.83.1/roadmap.md new file mode 100644 index 0000000000..7350801b89 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/roadmap.md @@ -0,0 +1,23 @@ +--- +title: Roadmap +sidebar_label: Roadmap +slug: '/roadmap' +--- + +:::tip +Kurtosis is rapidly evolving alongside the needs of our users. As a result, please interpret the below to be accurate for approximately 3 months from the last updated date. + +The last updated date is **August 1, 2023** +::: + +Over the next 1-3 months, we will be making investments in our product to enable workflows that involve long-lived environments. Doing so cements the value proposition that we offer for both dev and test, and opens a new world when it comes to production use cases. Directionally, these efforts represent a step closer to our goal of extending Kurtosis across the entire development lifecycle. Our investments will be spread across various features and improvements but will generally fall into one of the below buckets: + +- **More robust support for various workflows involving enclaves deployed on Kubernetes.** This includes support for graceful blue/green rollouts, support for replication controllers like ReplicaSet (RS), and cleaner ways to interact with the cluster from the outside. +- **Idempotent runs** that enable a developer to make changes to the Starlark package & Kurtosis will apply those changes to a long-lived enclave deterministically. +- **Frontend improvements** to support a cleaner interface for users to deploy & interact with a long-lived enclave in the cloud. These improvements would be in service of ensuring that the experience is as seamless and self-service as possible. +- **Connectivity to and from long-lived enclaves** to standardize, both from a user experience and technically, how one would get traffic to and from the enclave. This scope of work will include making it seamless to set up and manage the connection as well. +- **Persisting data** across enclaves, services within those enclaves, and beyond the lifecycle of a service and enclave as well. This includes the supporting workflows for trivial manipulation of the data inside a container. +- **Centralized logging infrastructure** to aggregate logs from everything inside an enclave, making them easily queryable, and storing them somewhere so that they can be used beyond the life of the enclave. +- **A fully managed cloud offering and accompanying self-service workflows** for a stress-free, easy way to deploy test and dev environments, that live as long as you ened them to, directly onto remote infrastructure. + +If any of the investments we are making interest you or if you have feedback for us, please let us know in our [Github Discussions](https://github.com/kurtosis-tech/kurtosis/discussions/categories/q-a) page, where we are fielding some great questions from our community. diff --git a/docs/versioned_docs/version-0.83.1/sdk.md b/docs/versioned_docs/version-0.83.1/sdk.md new file mode 100644 index 0000000000..da9570f7a8 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/sdk.md @@ -0,0 +1,570 @@ +--- +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) -> [EnclaveContext][enclavecontext] enclaveContext` +Creates a new Kurtosis enclave using the given parameters. The enclave will be created in default mode (when services fail, it won't restart) + +**Args** +* `enclaveName`: The name to give the new enclave. + +**Returns** +* `enclaveContext`: An [EnclaveContext][enclavecontext] object representing the new enclave. + +### `createProductionEnclave(String enclaveName) -> [EnclaveContext][enclavecontext] enclaveContext` +Same as above, but creates an enclave in production mode (services will restart upon failure) + + +### `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 successfully + +### `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 represents 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, List experimentalFeatureFlags, String connect) -> (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. +* `experimentalFeatureFlags`: List of experimental features to turn on for this run. Leave empty to leave any experimental feature disabled. +* `connect`: When set to 'CONNECT', the user service ports are forwarded. When set to 'NO_CONNECT', the user service ports are not forwarded. + +**Returns** + +* `responseLines`: A stream of [StarlarkRunResponseLine][starlarkrunresponseline] objects + +### `runStarlarkPackage(String packageRootPath, String relativePathToMainFile, String mainFunctionName, String serializedParams, Boolean dryRun, List experimentalFeatureFlags, String connect) -> (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. +* `experimentalFeatureFlags`: List of experimental features to turn on for this run. Leave empty to leave any experimental feature disabled. +* `connect`: When set to 'CONNECT', the user service ports are forwarded. When set to 'NO_CONNECT', the user service ports are not forwarded. + +**Returns** + +* `responseLines`: A stream of [StarlarkRunResponseLine][starlarkrunresponseline] objects + +### `runStarlarkRemotePackage(String packageId, String relativePathToMainFile, String mainFunctionName, String serializedParams, Boolean dryRun, String connect) -> (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. +* `connect`: When set to 'CONNECT', the user service ports are forwarded. When set to 'NO_CONNECT', the user service ports are not forwarded. + +**Returns** + +* `responseLines`: A stream of [StarlarkRunResponseLine][starlarkrunresponseline] objects + +### `runStarlarkScriptBlocking(String mainFunctionName, String serializedStarlarkScript, Boolean dryRun, String connect) -> (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, String connect) -> (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, String connect) -> (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. + +### [StarlarkRunFinishedEvent][starlarkrunfinishedevent] `runFinishedEvent` +This object will be sent _once_ at the end of the execution to signify it has ended. + +### [StarlarkWarning][starlarkwarning] `warning` +A warning, non-fatal, message + +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 happen 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 happen 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 happen 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. + +StarlarkRunFinishedEvent +------------------------ + +`StarlarkRunFinishedEvent` is the object returned when the execution of the Starlark code is finished. Is composed of two fields: + +* `isRunSuccessful`: whether the run successfully finished or not + +* `serializedOutput`: when the run is successful and the Starlark code has returned an object, the returned object is automatically serialized to JSON by Kurtosis and returned via this field. + +StarlarkWarning +--------------- + +`StarlarkWarning` is a warning message returned by Kurtosis Starlark engine. Warnings are by definition non-fatal, they typically point out an antipattern in the code or a deprecated feature still being used + +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-liststring-experimentalfeatureflags-string-connect---streamstarlarkrunresponseline-responselines-error-error +[enclavecontext_runstarlarkpackage]: #runstarlarkscriptstring-mainfunctionname-string-serializedstarlarkscript-boolean-dryrun-liststring-experimentalfeatureflags-string-connect---streamstarlarkrunresponseline-responselines-error-error +[enclavecontext_runstarlarkremotepackage]: #runstarlarkscriptstring-mainfunctionname-string-serializedstarlarkscript-boolean-dryrun-liststring-experimentalfeatureflags-string-connect---streamstarlarkrunresponseline-responselines-error-error + +[starlarkrunresponseline]: #starlarkrunresponseline +[starlarkinstruction]: #starlarkinstruction +[starlarkinstructionresult]: #starlarkinstructionresult +[starlarkerror]: #starlarkerror +[starlarkrunprogress]: #starlarkrunprogress +[starlarkrunfinishedevent]: #starlarkrunfinishedevent +[starlarkwarning]: #starlarkwarning +[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.83.1/starlark-reference/directory.md b/docs/versioned_docs/version-0.83.1/starlark-reference/directory.md new file mode 100644 index 0000000000..f4a57f5b49 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/starlark-reference/directory.md @@ -0,0 +1,35 @@ +--- +title: Directory +sidebar_label: Directory +--- + +The `Directory` constructor creates a `Directory` object that represents a directory inside an existing service (see +the [ServiceConfig][service-config] object). +Directory object can be either a files artifact or a persistent directory, depending on the arguments passed to the +constructor. + +```python +file_artifact_directory = Directory( + artifact_name=files_artifact_1, +) +# Or: +persistent_directory = Directory( + persistent_key="data-directory" +) +``` + +A directory composed of a files artifact will be automatically provisioned with the given files artifact content. In +the above example, `files_artifact_1` is a files 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). + +A persistent directory, as its name indicates, persists over service updates and restarts. It is uniquely identified +by its `persistent_key` and the service ID on which it is being used (a persistent directory cannot be shared across +multiple services). When it is first created, it will be empty. The service can write anything in it. When the service +gets updated, the data in it persists. It is particularly useful for a service's data directory, logs directory, etc. + + +[render-templates-reference]: ./plan.md#render_templates +[service-config]: ./service-config.md +[store-service-reference]: ./plan.md#store_service_files +[upload-files-reference]: ./plan.md#upload_files diff --git a/docs/versioned_docs/version-0.83.1/starlark-reference/exec-recipe.md b/docs/versioned_docs/version-0.83.1/starlark-reference/exec-recipe.md new file mode 100644 index 0000000000..0bf1575e00 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/starlark-reference/get-http-request-recipe.md b/docs/versioned_docs/version-0.83.1/starlark-reference/get-http-request-recipe.md new file mode 100644 index 0000000000..049c0dbee9 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/starlark-reference/import-module.md b/docs/versioned_docs/version-0.83.1/starlark-reference/import-module.md new file mode 100644 index 0000000000..368a060175 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/starlark-reference/import-module.md @@ -0,0 +1,30 @@ +--- +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 remote code from another package using an absolute import +remote = import_module("github.com/foo/bar/src/lib.star") + +# Simiarily, you can also import a specific version (e.g. 2.0) of an upstream package using an absolute import +remote_2 = import_module("github.com/foo/bar/src/lib.star@2.0") + +# Import local code from the same package using a relative import +local = import_module("./local.star") + +def run(plan): + # Use code from the imported module + remote.do_something(plan) + + local.do_something_else(plan) +``` + +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.83.1/starlark-reference/index.md b/docs/versioned_docs/version-0.83.1/starlark-reference/index.md new file mode 100644 index 0000000000..a62127dfae --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/starlark-reference/plan.md b/docs/versioned_docs/version-0.83.1/starlark-reference/plan.md new file mode 100644 index 0000000000..d97be9f8f7 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/starlark-reference/plan.md @@ -0,0 +1,691 @@ +--- +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 and needs to be formatted according to RFC 1035. + # Specifically, 1-63 lowercase alphanumeric characters with dashes and cannot start or end with dashes. + # Also service names have to start with a lowercase alphabet. + # 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. + +::: + +verify +------ + +The `verify` instruction throws an [Execution phase error][multi-phase-runs-reference] if the defined assertion fails. + +```python +plan.verify( + # The value currently being verified. + # 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.verify( + # Value can also be a runtime value derived from a `get_value` call + value = response["body"], + assertion = "==", + target_value = 200, +) +``` + +:::caution + +Verifications are typed, so running + +```python +plan.verify( + 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 [`verify`][verify] and [`wait`][wait]: + +```python +exec_recipe = ExecRecipe( + command = ["echo", "Hello, world"], +) + +result = plan.exec(service_name="my_service", recipe=exec_recipe) +plan.verify(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_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 [`verify`][verify] 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.verify(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) + +run_python +---------- + +The `run_python` instruction executes a one-time execution task. It runs the Python script specified by the mandatory field `run` on an image specified by the optional `image` field. + +```python + result = plan.run_python( + # The Python script to execute as a string + # This will get executed via '/bin/sh -c "python /tmp/python/main.py"'. + # Where `/tmp/python/main.py` is path on the temporary container; + # on which the script is written before it gets run + # MANDATORY + run = """ + import requests + response = requests.get("docs.kurtosis.com") + print(response.status_code) + """, + + # Arguments to be passed t o the Python script defined in `run` + # OPTIONAL (Default: []) + args = [ + some_other_service.ports["http"].url, + ], + + # Packages that the Python script requires which will be installed via `pip` + # OPTIONAL (default: []) + packages = [ + "selenium", + "requests", + ], + + # Image the Python script will be run on + # OPTIONAL (Default: python:3.11-alpine) + image = "python:3.11-alpine", + + # A mapping of path_on_task_where_contents_will_be_mounted -> files_artifact_id_to_mount + # For more information about file artifacts, see below. + # CAUTION: duplicate paths to files or directories to be mounted is not supported, and it will fail + # OPTIONAL (Default: {}) + files = { + "/path/to/file/1": files_artifact_1, + "/path/to/file/2": files_artifact_2, + }, + + # list of paths to directories or files that will be copied to a file artifact + # CAUTION: all the paths in this list must be unique + # OPTIONAL (Default:[]) + store = [ + # copies a file into a file artifact + "/src/kurtosis.txt", + + # copies the entire directory into a file artifact + "/src", + ], + + # The time to allow for the command to complete. If the Python script takes longer than this, + # Kurtosis will kill the script and mark it as failed. + # 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 180s + # OPTIONAL (Default: "180s") + wait="180s" + ) + + plan.print(result.code) # returns the future reference to the exit code + plan.print(result.output) # returns the future reference to the output + plan.print(result.file_artifacts) # returns the file artifact names that can be referenced later +``` + +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][files-artifacts-reference] name. + +The instruction returns a `struct` with [future references][future-references-reference] to the ouput and exit code of the Python script, alongside with future-reference to the file artifact names that were generated. +* `result.output` is a future reference to the output of the command +* `result.code` is a future reference to the exit code +* `result.files_artifacts` is a future reference to the names of the file artifacts that were generated and can be used by the `files` property of `ServiceConfig` or `run_sh` instruction. An example is shown below:- + +run_sh +------------- + +The `run_sh` instruction executes a one-time execution task. It runs the bash command specified by the mandatory field `run` on an image specified by the optional `image` field. + +```python + result = plan.run_sh( + # The command to run, as a string + # This will get executed via 'sh -c "$COMMAND"'. + # For example: 'sh -c "mkdir -p kurtosis && echo $(ls)"' + # MANDATORY + run = "mkdir -p kurtosis && echo $(ls)", + + # Image the command will be run on + # OPTIONAL (Default: badouralix/curl-jq) + image = "badouralix/curl-jq", + + # A mapping of path_on_task_where_contents_will_be_mounted -> files_artifact_id_to_mount + # For more information about file artifacts, see below. + # CAUTION: duplicate paths to files or directories to be mounted is not supported, and it will fail + # OPTIONAL (Default: {}) + files = { + "/path/to/file/1": files_artifact_1, + "/path/to/file/2": files_artifact_2, + }, + + # list of paths to directories or files that will be copied to a file artifact + # CAUTION: all the paths in this list must be unique + # OPTIONAL (Default:[]) + store = [ + # copies a file into a file artifact + "/src/kurtosis.txt", + + # copies the entire directory into a file artifact + "/src", + ], + + # The time to allow for the command to complete. If the command takes longer than this, + # Kurtosis will kill the command and mark it as failed. + # 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 180s + # OPTIONAL (Default: "180s") + wait="180s" + ) + + plan.print(result.code) # returns the future reference to the code + plan.print(result.output) # returns the future reference to the output + plan.print(result.file_artifacts) # returns the file artifact names that can be referenced later +``` + +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][files-artifacts-reference] name. + +The instruction returns a `struct` with [future references][future-references-reference] to the ouput and exit code of the command, alongside with future-reference to the file artifact names that were generated. + * `result.output` is a future reference to the output of the command + * `result.code` is a future reference to the exit code + * `result.files_artifacts` is a future reference to the names of the file artifacts that were generated and can be used by the `files` property of `ServiceConfig` or `run_sh` instruction. An example is shown below:- + +```python + + result = plan.run_sh( + run = "mkdir -p task && cd task && echo kurtosis > test.txt", + store = [ + "/task", + # using '*' will only copy the contents of the parent directory and not the directory itself to file artifact + # in this case, only test.txt will be stored and task directory will be ignored + "/task/*", + ], + ... + ) + + plan.print(result.files_artifacts) # prints ["blue_moon", "green_planet"] + + # blue_moon is name of the file artifact that contains task directory + # green_planet is the name of the file artifact that conatins test.txt file + + service_one = plan.add_service( + ..., + config=ServiceConfig( + name="service_one", + files={"/src": results.file_artifacts[0]}, # copies the directory task into service_one + ) + ) # the path to the file will look like: /src/task/test.txt + + service_two = plan.add_service( + ..., + config=ServiceConfig( + name="service_two", + files={"/src": results.file_artifacts[1]}, # copies the file test.txt into service_two + ), + ) # the path to the file will look like: /src/test.txt +``` + +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", +) +``` + +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", +) +``` + +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. + + +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 [verification][verify] does not succeed within a given period of time. + +If the assertion succeeds, `wait` returns the result of the given Recipe - i.e. the same output as [`plan.request`][request] or [`plan.exec`][exec]. + +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`][ready-condition], 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 +recipe_result = 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", +) + +# The assertion has passed, so we can use `recipe_result` just like the result of `plan.request` or `plan.exec` +plan.print(recipe_result["code"]) +``` + + + +[add-service]: #add_service +[add-services]: #add_services +[verify]: #verify +[extract]: #extract +[exec]: #exec +[request]: #request +[start-service]: #start_service +[stop-service]: #stop_service +[wait]: #wait + +[cli-run-reference]: ../cli-reference/run.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 + +[starlark-types-service-config]: ./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.83.1/starlark-reference/port-spec.md b/docs/versioned_docs/version-0.83.1/starlark-reference/port-spec.md new file mode 100644 index 0000000000..08982a21f7 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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`][add-service-reference]. + +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.83.1/starlark-reference/post-http-request-recipe.md b/docs/versioned_docs/version-0.83.1/starlark-reference/post-http-request-recipe.md new file mode 100644 index 0000000000..1481ee043a --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/starlark-reference/read-file.md b/docs/versioned_docs/version-0.83.1/starlark-reference/read-file.md new file mode 100644 index 0000000000..fd880895fd --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/starlark-reference/read-file.md @@ -0,0 +1,33 @@ +--- +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 +read_file( + # The Kurtosis locator of the file to read. + # MANDATORY + src = "LOCATOR", +) +``` + +For example: + +```python +# Reading a file from a remote package using an absolute locator +remote_contents = read_file( + src = "github.com/kurtosis-tech/datastore-army-package/README.md", +) + +# Reading a file from inside the same package using a relative locator +local_contents = read_file( + src = "./file.txt", +) +``` + + +[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.83.1/starlark-reference/ready-condition.md b/docs/versioned_docs/version-0.83.1/starlark-reference/ready-condition.md new file mode 100644 index 0000000000..7defa0e7c4 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/starlark-reference/service-config.md b/docs/versioned_docs/version-0.83.1/starlark-reference/service-config.md new file mode 100644 index 0000000000..da1694786e --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/starlark-reference/service-config.md @@ -0,0 +1,116 @@ +--- +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 -> Directory object or file artifact name + # For more info on what a Directory object is, see below + # + # OPTIONAL (Default: {}) + files = { + "path/to/files/artifact_1/": files_artifact_1, + "path/to/files/artifact_2/": Directory( + artifact_name=files_artifact_2, + ), + "path/to/persistent/directory/": Directory( + persistent_key="data-directory", + ), + }, + + # 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, + + # 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 [Directory][directory] object or files artifact name. +Using a `Directory` object with `artifact_name` is strictly equivalent to directly using the files artifact name as the value of the dictionary. This is just to simplify usage. + +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 +[directory]: ./directory.md +[port-spec]: ./port-spec.md +[ready-condition]: ./ready-condition.md diff --git a/docs/versioned_docs/version-0.83.1/starlark-reference/service.md b/docs/versioned_docs/version-0.83.1/starlark-reference/service.md new file mode 100644 index 0000000000..7024aad037 --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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.83.1/starlark-reference/standard-library.md b/docs/versioned_docs/version-0.83.1/starlark-reference/standard-library.md new file mode 100644 index 0000000000..c69a9434ce --- /dev/null +++ b/docs/versioned_docs/version-0.83.1/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). The `time.now()` function is disabled as it introduces non-determinism and users are encouraged to use `plan.run_python` in the meantime while we work on a suitable replacement. +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) +3. 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_sidebars/version-0.83.1-sidebars.json b/docs/versioned_sidebars/version-0.83.1-sidebars.json new file mode 100644 index 0000000000..892198172b --- /dev/null +++ b/docs/versioned_sidebars/version-0.83.1-sidebars.json @@ -0,0 +1,80 @@ +{ + "main": [ + "home", + { + "type": "link", + "label": "Kurtosis for Web3", + "href": "https://web3.kurtosis.com" + }, + "quickstart", + "code-examples", + { + "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", + "faq", + "best-practices", + "roadmap", + "changelog" + ] +} diff --git a/docs/versions.json b/docs/versions.json index 36973f6048..985c0915be 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,4 +1,5 @@ [ + "0.83.1", "0.83.0", "0.82.24", "0.81.9", diff --git a/version.txt b/version.txt index 83dcd12cbe..2a04905628 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -0.83.0 +0.83.1