Skip to content

Commit

Permalink
docs: revamp package consumer quickstart (#1805)
Browse files Browse the repository at this point in the history
## Description:
Simplifies package consumer quickstart and uses the
`basic-service-package` as a base

## Is this change user facing?
YES

## References (if applicable):
  • Loading branch information
galenmarchetti authored Nov 17, 2023
1 parent 00c317a commit 75cba6e
Show file tree
Hide file tree
Showing 15 changed files with 171 additions and 195 deletions.
34 changes: 11 additions & 23 deletions docs/docs/get-started/basic-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ Package

A package defines the set up logic for a containerized backend. Packages can be accessed via Github locators.

```bash
```console
kurtosis run github.com/kurtosis-tech/basic-service-package
```

Packages can accept a set of parameters, defined by the package author, which enable the package consumer to modify their deployed backend at a high-level without needing to know how to configure each individual service.

```bash
```console
kurtosis run github.com/kurtosis-tech/basic-service-package \
'{"service_a_count": 2,
"service_b_count": 2,
Expand All @@ -27,31 +27,19 @@ kurtosis run github.com/kurtosis-tech/basic-service-package \
Enclave
-----------

An enclave is a "walled garden" in which Kurtosis runs a containerized backend. Enclaves can run anywhere that you have a Docker engine or a Kubernetes cluster. The main purposes of an enclave are resource isolation and "garbage collection". With an "enclave remove" command (`kurtosis enclave rm`), you can destroy all of the resources used to set up your environment and leave nothing hanging around on your machine(s).
An enclave is a "walled garden" in which Kurtosis runs a containerized backend. Enclaves can run anywhere that you have a Docker engine or a Kubernetes cluster. The main purposes of an enclave are resource isolation and "garbage collection".

Plan
-----------

The "plan" is the series of instructions, encoded in a package, that runs in an enclave. Each instruction in a plan is a basic building block for spinning up a containerized backend. You can see the plan that a package will run by "dry-running" the package:

```bash
kurtosis run --dry-run github.com/kurtosis-tech/basic-service-package
```

<details><summary><b>Rendered Plan</b></summary>
With an "enclave remove" command (`kurtosis enclave rm`), you can destroy all of the resources used to set up your environment and leave nothing hanging around on your machine(s).

```title="Steps in the Plan"
> render_templates
> add_services configs={"service-a-1": ServiceConfig(image="h4ck3rk3y/service-a", ports={"frontend": PortSpec(number=8501, application_protocol="http")}, files={"/app/config": "slender-boulder"})}
> render_templates
Files Artifact
-----------

> add_services configs={"service-b-1": ServiceConfig(image="h4ck3rk3y/service-b", ports={"frontend": PortSpec(number=8501, application_protocol="http")}, files={"/app/config": "purple-comet"}, cmd=["false"])}
A files artifact is a set of files shipped with, or generated by, a package. Files artifacts are typically used for rendering configuration files that must be dynamically generated when an environment spins up, or for shipping static configuration files that must be shared across multiple services.

> render_templates
When you run a package, you can see the files artifacts that the package uses in the enclave output:

> add_services configs={"service-c-1": ServiceConfig(image="h4ck3rk3y/service-c", ports={"frontend": PortSpec(number=8501, application_protocol="http")}, files={"/app/config": "arctic-oak"}, env_vars={"PARTY_MODE": "false"})}
```console
kurtosis run github.com/kurtosis-tech/basic-service-package
```

</details>
![files-artifact-output-concepts.png](/img/home/files-artifact-output-concepts.png)
8 changes: 4 additions & 4 deletions docs/docs/get-started/get-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ To quickly see what Kurtosis feels like, check out the example snippets below:

### Local Deploy on Docker

```bash
```console
kurtosis run github.com/kurtosis-tech/basic-service-package
```

Expand All @@ -34,7 +34,7 @@ kurtosis run github.com/kurtosis-tech/basic-service-package

### Local deploy with feature flag and different numbers of each service

```bash
```console
kurtosis run github.com/kurtosis-tech/basic-service-package \
'{"service_a_count": 2,
"service_b_count": 2,
Expand All @@ -56,10 +56,10 @@ kurtosis run github.com/kurtosis-tech/basic-service-package \

### Remote deploy on Kubernetes

```bash
```console
kurtosis cluster set remote-kubernetes; kurtosis gateway > /dev/null 2>&1 &
```
```bash
```console
kurtosis run github.com/kurtosis-tech/basic-service-package \
'{"service_a_count": 2,
"service_b_count": 2,
Expand Down
25 changes: 6 additions & 19 deletions docs/docs/get-started/installing-the-cli.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Installing Kurtosis
title: Install Kurtosis
id: installing-the-cli
sidebar_label: Installing Kurtosis
sidebar_label: Install Kurtosis
slug: /install
sidebar_position: 2
---
Expand All @@ -13,31 +13,18 @@ import TabItem from '@theme/TabItem';

<!---------- END IMPORTS ------------>


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].
The instructions in this guide will walk you through installing the latest version of Kurtosis.

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:
2. Start the Docker daemon (e.g. open Docker Desktop)
3. Verify that Docker is running:
```bash
docker image ls
```

:::note
For some users, Kurtosis fails to run if Docker was not installed in `sudo` mode. We have a workaround detailed in [#1140](https://github.com/kurtosis-tech/kurtosis/issues/1140) while we work on a more graceful solution, outlined in [#1469](https://github.com/kurtosis-tech/kurtosis/issues/1469).
:::

II. Install the CLI
-------------------------

Expand Down Expand Up @@ -134,7 +121,7 @@ kurtosis version
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].
Kurtosis supports optional command-line completion to allow completing subcommands and dynamic values (e.g. enclave name during `enclave inspect`). If you'd like to install it, see [these instructions][installing-command-line-completion].
Run the quickstart
------------------
Expand Down
Loading

0 comments on commit 75cba6e

Please sign in to comment.