Apply automatic changes

LICENSE.md

@@ -3,7 +3,7 @@ Business Source License 1.1
 Parameters
 
 Licensor:             Kurtosis Technologies, Inc.
-Licensed Work:        Kurtosis 0.78.2
+Licensed Work:        Kurtosis 0.78.3
 The Licensed Work is (c) 2023 Kurtosis Technologies, Inc.
 Additional Use Grant: You may make use of the Licensed Work, provided that
 you may not use the Licensed Work for an Environment Orchestration Service.

api/golang/kurtosis_version/kurtosis_version.go

@@ -9,6 +9,6 @@ const (
 	// !!!!!!!!!!! DO NOT UPDATE! WILL BE MANUALLY UPDATED DURING THE RELEASE PROCESS !!!!!!!!!!!!!!!!!!!!!!
 	// This is necessary so that Kurt Core consumers will know if they're compatible with the currently-running
 	//  API container
-	KurtosisVersion = "0.78.2"
+	KurtosisVersion = "0.78.3"
 	// !!!!!!!!!!! DO NOT UPDATE! WILL BE MANUALLY UPDATED DURING THE RELEASE PROCESS !!!!!!!!!!!!!!!!!!!!!!
 )

api/typescript/package.json

@@ -1,7 +1,7 @@
 {
     "name": "kurtosis-sdk",
     "//": "NOTE: DO NOT UPDATE THIS VERSION MANUALLY - IT WILL BE UPDATED DURING THE RELEASE PROCESS!",
-    "version": "0.78.2",
+    "version": "0.78.3",
     "main": "./build/index",
     "description": "This repo contains a Typescript client for communicating with the Kurtosis Engine server, which is responsible for creating, managing and destroying Kurtosis Enclaves.",
     "types": "./build/index",

api/typescript/src/kurtosis_version/kurtosis_version.ts

@@ -1,5 +1,5 @@
 // !!!!!!!!!!! DO NOT UPDATE! WILL BE MANUALLY UPDATED DURING THE RELEASE PROCESS !!!!!!!!!!!!!!!!!!!!!!
 // This is necessary so that Kurt Core consumers (e.g. modules) will know if they're compatible with the currently-running
 //  API container
-export const KURTOSIS_VERSION: string = "0.78.2"
+export const KURTOSIS_VERSION: string = "0.78.3"
 // !!!!!!!!!!! DO NOT UPDATE! WILL BE MANUALLY UPDATED DURING THE RELEASE PROCESS !!!!!!!!!!!!!!!!!!!!!!

docs/versioned_docs/version-0.78.3/best-practices.md

@@ -0,0 +1,44 @@
+---
+title: Best Practices
+sidebar_label: Best Practices
+slug: /best-practices
+---
+
+Passing package arguments to the CLI
+-------------------------------
+Passing [package arguments][args-concepts-reference] to the CLI can get hairy due to the interaction between Bash and JSON quotes. The following are tips to make your life easier:
+
+1. **When you have a small number of arguments:** surround the arguments with single quotes so you don't have to escape double quotes in your JSON. E.g.:
+   ```bash
+   kurtosis run github.com/user/repo '{"some_param":5,"some_other_param":"My value"}'
+   ```
+1. **When you have a large number of arguments:** put them in a `.json` file and use [Bash command substitution](https://www.gnu.org/software/bash/manual/html_node/Command-Substitution.html) _inside double quotes_ to slot them into the `kurtosis run` command. E.g.:
+   ```bash
+   kurtosis run github.com/user/repo "$(cat my-args.json)"
+   ```
+   The double quotes around the `$(cat my-args.json)` are important so any spaces inside `my-args.json` don't fool Bash into thinking you're passing in two separate arguments.
+
+Choosing the right wait
+-----------------------
+Kurtosis has three different types of waits. Described here are the three, with tips on when to use each:
+
+1. Automatic waiting on port availability when a service starts (enabled by default; can be configured with [`PortSpec.wait`][port-spec-starlark-reference])
+    - Should be sufficient for most usecases
+    - Requires little-to-no extra configuration
+    - Will cause parallel `Plan.add_services` to fail, allowing for quick aborting
+1. Waiting on [`ReadyCondition`][ready-condition-starlark-reference]s (configured in [`ServiceConfig`][service-config-starlark-reference])
+    - Allows for more advanced checking (e.g. require a certain HTTP response body, ensure a CLI call returns success, etc.)
+    - More complex to configure
+    - Will cause parallel `Plan.add_services` to fail, allowing for quick aborting
+1. The [`Plan.wait`][plan-wait-starlark-reference]
+    - Most useful for asserting the system has reached a desired state in tests (e.g. wait until data shows up after loading)
+    - More complex to configure
+    - Cannot be used to short-circuit `Plan.add_services`
+
+<!---------------------------------------- ONLY LINKS BELOW HERE!!! ----------------------------------->
+[args-concepts-reference]: ./concepts-reference/args.md
+
+[service-config-starlark-reference]: ./starlark-reference/service-config.md
+[port-spec-starlark-reference]: ./starlark-reference/port-spec.md
+[ready-condition-starlark-reference]: ./starlark-reference/ready-condition.md
+[plan-wait-starlark-reference]: ./starlark-reference/plan.md#wait

docs/versioned_docs/version-0.78.3/cli-reference/analytics-disable.md

@@ -0,0 +1,13 @@
+---
+title: analytics disable
+sidebar_label: analytics disable
+slug: /analytics-disable
+---
+
+Kurtosis has functionality to collect product analytics metrics so we can make data-driven product decisions. These metrics are [anonymized, obfuscated, and never given to third parties](../explanations/metrics-philosophy.md)).
+
+Anonymous metrics collection is enabled by default, but you can turn it off by running:
+
+```bash
+kurtosis analytics disable
+``` 

docs/versioned_docs/version-0.78.3/cli-reference/analytics-enable.md

@@ -0,0 +1,13 @@
+---
+title: analytics enable
+sidebar_label: analytics enable
+slug: /analytics-enable
+---
+
+Kurtosis has functionality to collect product analytics metrics so we can make data-driven product decisions. These metrics are [anonymized, obfuscated, and never given to third parties](../explanations/metrics-philosophy.md)).
+
+If you previously disabled metrics collection, you can re-enable it via:
+
+```bash
+kurtosis analytics enable
+``` 

docs/versioned_docs/version-0.78.3/cli-reference/analytics-id.md

@@ -0,0 +1,15 @@
+---
+title: analytics id
+sidebar_label: analytics id
+slug: /analytics-id
+---
+
+In addition to log outputs and screenshots, [product analytics metrics](../explanations/metrics-philosophy.md) may be useful for our team when debugging issues and shipping fixes for bugs. 
+
+If you so choose, you may share with us your metrics user ID when letting us know about issues or bugs (in our [Github](https://github.com/kurtosis-tech/kurtosis/issues/new/choose) or on [Discord](https://discord.gg/rjkj8m5C)). Doing helps us debug issues, ship fixes quicker, and ultimately improve Kurtosis over time.
+
+To print your metrics user ID, simply run:
+
+```bash
+kurtosis analytics id
+``` 

docs/versioned_docs/version-0.78.3/cli-reference/clean.md

@@ -0,0 +1,18 @@
+---
+title: clean
+sidebar_label: clean
+slug: /clean
+---
+
+```console
+Removes stopped enclaves (and live ones if the 'all' flag is set), as well as stopped engine containers
+
+Usage:
+  kurtosis clean [flags]
+
+Flags:
+  -a, --all    If set, removes running enclaves as well
+  -h, --help   help for clean
+```
+
+NOTE: This will not stop the Kurtosis engine itself! To do so, use the [engine stop](./engine-stop.md) command.

docs/versioned_docs/version-0.78.3/cli-reference/completion.md

@@ -0,0 +1,20 @@
+---
+title: completion
+sidebar_label: completion
+slug: /completion
+---
+
+Scripts used to create command-line completion for `bash`, `fish`, `powershell`, and `zsh` can be printed using:
+
+```bash
+kurtosis completion [command]
+```
+
+The available commands are as follows:
+
+* `bash`: Generates the autocompletion script for bash
+* `fish`: Generates the autocompletion script for fish
+* `powershell`: Generates the autocompletion script for powershell
+* `zsh`: Generates the autocompletion script for zsh
+
+Instructions for how to install command-line completion on your shell can be found [here](../guides/adding-command-line-completion.md) in our Guides section.

docs/versioned_docs/version-0.78.3/cli-reference/config-path.md

@@ -0,0 +1,7 @@
+---
+title: config path
+sidebar_label: config path
+slug: /config-path
+---
+
+The `kurtosis config path` command displays the path to the Kurtosis CLI config YAML file. This file is used to configure Kurtosis CLI behaviour.

docs/versioned_docs/version-0.78.3/cli-reference/discord.md

@@ -0,0 +1,11 @@
+---
+title: discord
+sidebar_label: discord
+slug: /discord
+---
+
+The following command can be used to open our Discord server from the CLI where you can join our Discord to ask questions, chat with our team, and meet the community:
+
+```bash
+kurtosis discord
+```

docs/versioned_docs/version-0.78.3/cli-reference/docs.md

@@ -0,0 +1,13 @@
+---
+title: docs
+sidebar_label: docs
+slug: /docs
+---
+
+To open our documentation in the browser from the CLI, run:
+
+```bash
+kurtosis docs
+```
+
+where you can learn more about Kurtosis' architecture, APIs, Starlark, and much more.

docs/versioned_docs/version-0.78.3/cli-reference/dump.md

@@ -0,0 +1,17 @@
+---
+title: dump
+sidebar_label: dump
+slug: /dump
+---
+
+You might need to store the entire state of Kurtosis to disk at some point. You may want to have a log package if your CI fails, or you want to send debugging information to [the author of a Kurtosis package][packages-reference]. Whatever the case may be, you can run:
+
+```bash
+kurtosis dump $OUTPUT_DIRECTORY
+```
+You will get the container logs & configuration in the output directory for further analysis & sharing. This would contain all engines & enclaves.
+
+If you don't specify the `$OUTPUT_DIRECTORY` Kurtosis will dump it to a directory with a name following the schema `kurtosis-dump--TIMESTAMP`.
+
+<!-------------------- ONLY LINKS BELOW THIS POINT ----------------------->
+[packages-reference]: ../concepts-reference/packages.md

docs/versioned_docs/version-0.78.3/cli-reference/enclave-add.md

@@ -0,0 +1,17 @@
+---
+title: enclave add
+sidebar_label: enclave add
+slug: /enclave-add
+---
+
+Your distributed applications run in [enclaves][enclaves-reference]. They are isolated from each other, to ensure they don't interfere with each other. To create a new, empty enclave, simply run:
+
+```bash
+kurtosis enclave add
+```
+
+To create enclaves that support [subnetworks][subnetworks] use the `--with-subnetworks` flag.
+
+<!-------------------- ONLY LINKS BELOW THIS POINT ----------------------->
+[enclaves-reference]: ../concepts-reference/enclaves.md
+[subnetworks]: ../concepts-reference/subnetworks.md

docs/versioned_docs/version-0.78.3/cli-reference/enclave-dump.md

@@ -0,0 +1,20 @@
+---
+title: enclave dump
+sidebar_label: enclave dump
+slug: /enclave-dump
+---
+
+You will likely need to store enclave logs to disk at some point. You may want to have a log package if your CI fails, or you want to send debugging information to [the author of a Kurtosis package][packages-reference]. Whatever the case may be, you can run:
+
+```bash
+kurtosis enclave dump $THE_ENCLAVE_IDENTIFIER $OUTPUT_DIRECTORY
+```
+where the `$THE_ENCLAVE_IDENTIFIER` is the [resource identifier](../concepts-reference/resource-identifier.md) for an enclave.
+
+You will get the container logs & configuration in the output directory for further analysis & sharing.
+
+If you don't specify the `$OUTPUT_DIRECTORY` Kurtosis will dump it to a directory with a name following the `ENCLAVE_NAME--ENCLAVE_UUID` scheme in the
+current working directory.
+
+<!-------------------- ONLY LINKS BELOW THIS POINT ----------------------->
+[packages-reference]: ../concepts-reference/packages.md

docs/versioned_docs/version-0.78.3/cli-reference/enclave-inspect.md

@@ -0,0 +1,23 @@
+---
+title: enclave inspect
+sidebar_label: enclave inspect
+slug: /enclave-inspect
+---
+
+To view detailed information about a given enclave, including its status and contents, run:
+
+```bash
+kurtosis enclave inspect $THE_ENCLAVE_IDENTIFIER 
+```
+
+where `$THE_ENCLAVE_IDENTIFIER` is the [resource identifier](../concepts-reference/resource-identifier.md) for the enclave.
+
+Running the above command will print detailed information about:
+
+- The enclave's status (running or stopped)
+- The services inside the enclave (if any), their status, and the information for accessing those services' ports from your local machine
+- Any files artifacts registered within the specified enclave
+
+By default, UUIDs are shortened. To view the full UUIDs of your resources, add the following flag:
+* `--full-uuids`
+

docs/versioned_docs/version-0.78.3/cli-reference/enclave-ls.md

@@ -0,0 +1,13 @@
+---
+title: enclave ls
+sidebar_label: enclave ls
+slug: /enclave-ls
+---
+
+To print all enclaves (both stopped and running) inside of your Kurtosis engine, use:
+
+```bash
+kurtosis enclave ls
+```
+
+The enclave UUIDs and names that are printed will be used in enclave manipulation commands and are refered to as [resource identifiers](../concepts-reference/resource-identifier.md).

docs/versioned_docs/version-0.78.3/cli-reference/enclave-rm.md

@@ -0,0 +1,14 @@
+---
+title: enclave rm
+sidebar_label: enclave rm
+slug: /enclave-rm
+---
+
+To remove an enclave and all resources associated with that particular enclave, use:
+
+```bash
+kurtosis enclave rm $THE_ENCLAVE_IDENTIFIER 
+```
+where `$THE_ENCLAVE_IDENTIFIER` is the enclave [identifier](../concepts-reference/resource-identifier.md).
+
+Note that this command will only remove stopped enclaves. To destroy a running enclave, pass the `-f`/`--force` flag.

docs/versioned_docs/version-0.78.3/cli-reference/enclave-stop.md

@@ -0,0 +1,16 @@
+---
+title: enclave stop
+sidebar_label: enclave stop
+slug: /enclave-stop
+---
+
+To stop a particular enclave, use:
+
+```bash
+kurtosis enclave stop $THE_ENCLAVE_IDENTIFIER 
+```
+where `$THE_ENCLAVE_IDENTIFIER` is the enclave [identifier](../concepts-reference/resource-identifier.md).
+
+:::caution
+Enclaves that have been stopped cannot currently be restarted. The Kurtosis team is actively working on enabling this functionality.
+:::

docs/versioned_docs/version-0.78.3/cli-reference/engine-logs.md

@@ -0,0 +1,13 @@
+---
+title: engine logs
+sidebar_label: engine logs
+slug: /engine-logs
+---
+
+To get logs for all existing (stopped or running) engines, use:
+
+```bash
+kurtosis engine logs $OUTPUT_DIRECTORY
+```
+
+which will dump all the logs of the engine container to the directory specified by `$OUTPUT_DIRECTORY`. If a `$OUTPUT_DIRECTORY` is not specified, Kurtosis will default to writing the logs in a folder name following the schema `kurtosis-engine-logs--TIMESTAMP` in the working directory.

docs/versioned_docs/version-0.78.3/cli-reference/engine-restart.md

@@ -0,0 +1,11 @@
+---
+title: engine restart
+sidebar_label: engine restart
+slug: /engine-restart
+---
+
+The CLI interacts with the Kurtosis engine, which is a very lightweight container. The CLI will start the engine container automatically for you and you should never need to start it manually, but you might need to restart the engine after a CLI upgrade. To do so, run:
+
+```bash
+kurtosis engine restart
+```

docs/versioned_docs/version-0.78.3/cli-reference/engine-start.md

@@ -0,0 +1,16 @@
+---
+title: engine start
+sidebar_label: engine start
+slug: /engine-start
+---
+
+The Kurtosis engine starts automatically when you run any command that interacts with the engine, such as [`kurtosis enclave add`](./enclave-add.md), but there may be times where the engine has been stopped and you may need to start it again (e.g. starting the engine on a specific version). To do so, run:
+
+```bash
+kurtosis engine start
+```
+This command will do nothing if the Kurtosis engine is already running.
+
+You may optionally pass in the following flags with this command:
+* `--log-level`: The level that the started engine should log at. Options include: `panic`, `fatal`, `error`, `warning`, `info`, `debug`, or `trace`. The engine logs at the `info` level by default.
+* `--version`: The version (Docker tag) of the Kurtosis engine that should be started. If not set, the engine will start up with the default version.

docs/versioned_docs/version-0.78.3/cli-reference/engine-status.md

@@ -0,0 +1,11 @@
+---
+title: engine status
+sidebar_label: engine status
+slug: /engine-status
+---
+
+The engine's version and status can be printed with:
+
+```bash
+kurtosis engine status
+```

docs/versioned_docs/version-0.78.3/cli-reference/engine-stop.md

@@ -0,0 +1,13 @@
+---
+title: engine stop
+sidebar_label: engine stop
+slug: /engine-stop
+---
+
+To stop the engine, run:
+
+```bash
+kurtosis engine stop
+```
+
+Note that this will do nothing if there is no engine running.