chore(main): release 0.69.1 (#291)

🤖 I have created a release *beep* *boop*
---


##
[0.69.1](0.69.0...0.69.1)
(2023-03-22)


### Features

* Add `context` root command and simple `ls` subcommand
([#241](#241))
([4097c25](4097c25))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: kurtosisbot <kurtosisbot@users.noreply.github.com>
Co-authored-by: Gyanendra Mishra <anomaly.the@gmail.com>

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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)
 
 

LICENSE.md

@@ -3,7 +3,7 @@ Business Source License 1.1
 Parameters
 
 Licensor: Kurtosis Technologies, Inc.
-Licensed Work: Kurtosis 0.69.0
+Licensed Work: Kurtosis 0.69.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.
@@ -12,7 +12,7 @@ you may not use the Licensed Work for an Environment Orchestration Service.
   allows third parties (other than your employees and
   contractors) to create distributed system environments.
 
-Change Date: 2027-03-21
+Change Date: 2027-03-22
 
 Change License: AGPLv3 (GNU Affero General Public License Version 3)
 

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.69.0"
+ KurtosisVersion = "0.69.1"
  // !!!!!!!!!!! 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.69.0",
+ "version": "0.69.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",

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.69.0"
+export const KURTOSIS_VERSION: string = "0.69.1"
 // !!!!!!!!!!! DO NOT UPDATE! WILL BE MANUALLY UPDATED DURING THE RELEASE PROCESS !!!!!!!!!!!!!!!!!!!!!!

docs/versioned_docs/version-0.69.1/explanations/architecture.md

@@ -0,0 +1,68 @@
+---
+title: Kurtosis Architecture
+sidebar_label: Architecture
+sidebar_position: 2
+---
+
+![Kurtosis Architecture](@site/static/img/explanations/kurtosis-architecture.png)
+
+Kurtosis At A Macro Level
+-------------------------
+At a macro level, Kurtosis is an engine (a set of Kurtosis servers) deployed on top of a container orchestrator (e.g. Docker, Kubernetes). All interaction with Kurtosis is done via the Kurtosis APIs. After the Kurtosis engine receives a request, it usually modifies some state inside the container orchestrator. Kurtosis therefore serves as an abstraction layer atop the container orchestrator, so that code written for Kurtosis is orchestrator-agnostic.
+
+To understand what the Kurtosis engine 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][what-is-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 the Kurtosis engine is to receive requests from the client and translate them to instructions for the underlying container orchestration engine. These requests can be simple commands that map 1:1 to instructions to the underlying container orchestrator (e.g. "add service X to environment Y"), or they can be Kurtosis-only commands that require complex interaction with the container orchestrator (e.g. "divide environment X in two with a simulated network partition").
+
+Enclaves
+--------
+Kurtosis implements "environments as a first-class" concept using **enclaves**. An enclave can be thought of an "environment container" - an isolated place for a user to run an environment that is easy to create, manage, and destroy. Each enclave is separate from the other enclaves: no network communication can happen between them. Enclaves are also cheap: each Kurtosis engine can manage arbitrary numbers of enclaves, limited only by the underlying hardware.
+
+Example: Some enclaves running in a Kurtosis engine, as displayed by [the Kurtosis CLI][installation]:
+
+```
+EnclaveUUID Name Status Creation Time
+a525cee593af4b45aa15785e87d3b7c9 local RUNNING Thu, 24 Nov 2022 14:11:27 UTC
+edf36be917504e449a1648cf8d6c78a4 test RUNNING Thu, 24 Nov 2022 14:11:34 UTC
+```
+
+Services
+--------
+Enclaves contain distributed applications, and distributed applications have services. A service in Kurtosis is a container that exposes ports, and services may 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:
+
+```
+Enclave UUID: 2e42f9fd7b854eabb04f71a15bd1b55f
+Enclave Name: test
+Enclave Status: RUNNING
+Creation Time: Thu, 24 Nov 2022 11:11:34 -03
+API Container Status: RUNNING
+API Container Host GRPC Port: 127.0.0.1:60768
+API Container Host GRPC Proxy Port: 127.0.0.1:60769
+
+========================================== 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
+```
+
+SDKs
+----
+All interaction with Kurtosis happens via API requests to the Kurtosis engine. To assist with calling the API, [we provide SDKs in various languages](https://github.com/kurtosis-tech/kurtosis-sdk). Anything the Kurtosis engine is capable of doing will be available via the API and, therefore, via the SDKs.
+
+For day-to-day operation, we also provide [a CLI ][installation] (usage guide [here][cli-usage]). This is a Go CLI that uses the Go SDK underneath.
+
+Kurtosis Instruction Language
+-----------------------------
+Distributed system definitions are complex. To allow users to express their system in the simplest way possible while still fulfilling the required [properties of a reusable environment definition][reusable-environment-definitions], the Kurtosis engine provides users with the ability [to define and manipulate enclaves using Google's Starlark configuration language][starlark-explanation]. The Kurtosis engine contains a Starlark interpreter, and users can [send Starlark instructions][starlark-instructions] via the Kurtosis SDK to tell the engine what to do with an enclave. This allows users to define their environments as code.
+
+For a reference list of the available Starlark instructions, [see here][starlark-instructions].
+
+<!-------------- ONLY LINKS BELOW HERE --------------------->
+[installation]: ../guides/installing-the-cli.md
+[cli-usage]: ../reference/cli/cli.md
+[reusable-environment-definitions]: ./reusable-environment-definitions.md
+[what-is-kurtosis]: ./what-is-kurtosis.md
+[starlark-explanation]: ./starlark.md
+[starlark-instructions]: ../reference/starlark-instructions.md

docs/versioned_docs/version-0.69.1/explanations/how-do-kurtosis-imports-work.md

@@ -0,0 +1,143 @@
+---
+title: How Do Kurtosis Imports Work?
+sidebar_label: How Do Kurtosis Imports Work?
+---
+
+### Background
+Kurtosis allows a [Starlark script][starlark-explanation] to use content from other files. This might be importing code from another Starlark file (via the `import_module` [instruction][starlark-instructions-reference]), or using contents of a static file (via the `read_file` [instruction][starlark-instructions-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. 
+
+<details>
+<summary>Click to see examples</summary>
+
+- 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.
+
+</details>
+:::
+
+### 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-sdk/blob/main/api/golang/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`
+:::
+
+<!-- 
+ It seems to me that we are suggesting users to use arbitrary name, only to change later; my worry is that it
+ could lead to import errors! With introduction of sub-packages, this could lead to even more confusion. If the users'
+ want to do this for quick testing, they can but we should not suggest it.
+-->
+:::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.
+:::
+
+<!---------------------- ONLY LINKS BELOW HERE ---------------------------->
+[starlark-explanation]: ./starlark.md
+[starlark-instructions-reference]: ../reference/starlark-instructions.md
+[kurtosis-yml-reference]: ../reference/kurtosis-yml.md
+[packages-reference]: ../reference/packages.md
+[locators-reference]: ../reference/locators.md

docs/versioned_docs/version-0.69.1/explanations/metrics-philosophy.md

@@ -0,0 +1,17 @@
+---
+title: Metrics Philosophy
+sidebar_label: Metrics Philosophy
+---
+
+Kurtosis is a small startup, which means that understanding how users are using the product is vital to our success. To this end, we've built the capability for Kurtosis to send product analytics metrics.
+
+However, user metrics are abused heavily in today's world - data is collected without the ability to disable analytics, intentionally deanonymized, and sold to third parties. We hate it as much as we're guessing you do.
+
+It was therefore important to us to collect our product analytic metrics ethically. Concretely, this means that we've made our metrics:
+
+1. Private: we will **never** give or sell your data to third parties
+1. Anonymized: your user ID is a hash, so we don't know who you are
+1. Obfuscated: potentially-sensitive parameters (e.g. enclave IDs) are hashed as well
+1. Opt-out: Kurtosis allows you to [easily switch off analytics](../reference/cli/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.