fix: bugs in K8s port-forwarding

kitproj · Jan 5, 2025 · 53cae75 · 53cae75
1 parent 3d0efb8
commit 53cae75
Show file tree

Hide file tree

Showing 11 changed files with 294 additions and 117 deletions.
diff --git a/README.md b/README.md
@@ -10,35 +10,48 @@ Make the dev loop crazy fast.
 
 ## What
 
-Kit is a software development tool designed to turbo-charge the software development process. 
+Kit is a software development tool designed to turbo-charge the software development process.
 
-Kit combines both task execution (like Foreman), container management (like Docker Compose), Kubernetes-like features (like Tilt, Skaffold), and a focus on local development (like Garden) in a single, easy-to-use binary.
+Kit combines both task execution (like Foreman), container management (like Docker Compose), Kubernetes-like features (
+like Tilt, Skaffold), and a focus on local development (like Garden) in a single, easy-to-use binary.
 
 It is designed to work seamlessly with both local-dev and cloud-dev environments, such as Codespaces and Gitpod.
 
 [![Watch the video](https://img.youtube.com/vi/IafQwT1rYOU/hqdefault.jpg)](https://youtu.be/IafQwT1rYOU)
 
-
 Key features of Kit include:
 
-* **Local testing**: Kit is designed for local testing, allowing developers to test their code on their local machines before pushing it to a test environment or production. This speeds up the testing process and helps developers catch and fix bugs more quickly.
-* **First-class container support**: Kit downloads and runs containers, allowing developers to test their code in a containerized environment without having to set up a separate container management system.
-* **First-class Kubernetes support**: Kit can deploy manifests to a cluster and automatically port-forward to the cluster.
-* **Advanced DAG architecture**: Kit's directed acyclic graph (DAG) structure allows for optimized parallel processing, reducing the time required for testing and speeding up the development process.
-* **Probes**: You can specify liveness probes for your tasks to see if they're working, automatically restarting them when they go wrong. You can also specify readiness probes for your tasks to see if they're ready.
-* **Dependency management**: You can specify dependencies between tasks, so when upstream tasks become successful or ready, downstream tasks are automatically started.
-* **Comprehensive container management**: Kit can manage both host processes and containers, providing a comprehensive view of the entire software system and quickly identifying any issues or bugs that arise.
-* **Automatic rebuilding and restarting**: Kit can automatically rebuild and restart applications in response to changes in the source code or configuration files, allowing developers to test their code quickly and efficiently.
+* **Local testing**: Kit is designed for local testing, allowing developers to test their code on their local machines
+  before pushing it to a test environment or production. This speeds up the testing process and helps developers catch
+  and fix bugs more quickly.
+* **First-class container support**: Kit downloads and runs containers, allowing developers to test their code in a
+  containerized environment without having to set up a separate container management system.
+* **First-class Kubernetes support**: Kit can deploy manifests to a cluster and automatically port-forward to the
+  cluster.
+* **Advanced DAG architecture**: Kit's directed acyclic graph (DAG) structure allows for optimized parallel processing,
+  reducing the time required for testing and speeding up the development process.
+* **Probes**: You can specify liveness probes for your tasks to see if they're working, automatically restarting them
+  when they go wrong. You can also specify readiness probes for your tasks to see if they're ready.
+* **Dependency management**: You can specify dependencies between tasks, so when upstream tasks become successful or
+  ready, downstream tasks are automatically started.
+* **Comprehensive container management**: Kit can manage both host processes and containers, providing a comprehensive
+  view of the entire software system and quickly identifying any issues or bugs that arise.
+* **Automatic rebuilding and restarting**: Kit can automatically rebuild and restart applications in response to changes
+  in the source code or configuration files, allowing developers to test their code quickly and efficiently.
 * **Parameterizable** Kit allows you to run tasks with different parameters.
-* **Flexible integration and extensibility**: Kit is designed to be highly flexible and extensible, with support for a wide range of programming languages, frameworks, and tools. It can be easily integrated with existing systems and customized to meet specific needs.
-* **Terminal output**: Tasks run concurrently and their status is muxed into a single terminal window, so you're not overwhelmed by pages of terminal output.
+* **Flexible integration and extensibility**: Kit is designed to be highly flexible and extensible, with support for a
+  wide range of programming languages, frameworks, and tools. It can be easily integrated with existing systems and
+  customized to meet specific needs.
+* **Terminal output**: Tasks run concurrently and their status is muxed into a single terminal window, so you're not
+  overwhelmed by pages of terminal output.
 * **Log capture**: Logs are captured so you can look at them anytime.
 
 Kit was written with extensive help from AI.
 
 ## Install
 
-Like `jq`, `kit` is a small standalone binary. You can download it from the [releases page](https://github.com/kitproj/kit/releases/latest). 
+Like `jq`, `kit` is a small standalone binary. You can download it from
+the [releases page](https://github.com/kitproj/kit/releases/latest).
 
 If you're on MacOS, you can use `brew`:
 
@@ -57,23 +70,7 @@ We do not support `go install`.
 
 ## Usage
 
-Apps are described by a DAG, for example:
-
-
-```mermaid
----
-title: Example of an app
----
-flowchart LR
-    api(name: api\ncommand: java -jar target/api.jar\nworkingDir: ./api\nports: 8080):::host --> build-api(name: build-api\ncommand: mvn package\nworkingDir: ./api\nwatch: ./api):::host
-    api --> mysql(name: mysql\n image: mysql:latest):::container
-    processor(name: processor\ncommand: ./processor):::host --> build-processor(name: build-processor\ncommand: go build ./processor\nwatch: ./processor):::host
-    processor --> kafka(name: kafka\nimage: ./src/images/kafka):::container
-    processor --> object-storage(name: object-storage\nimage: minio:latest):::container
-    processor --> api
-    ui(name: ui\ncommand: yarn start\nworkingDir: ./ui\nports: 4000):::host --> build-ui(name: build-ui\ncommand: yarn install\nworkingDir: ./ui):::host
-    ui --> api
-```
+Apps are described by a directed acyclic graph (DAG) of tasks.
 
 Create a [`tasks.yaml`](tasks.yaml) file, e.g.:
 
@@ -84,31 +81,80 @@ metadata:
   name: my-proj
 spec:
   tasks:
-    - command: go build -v .
-      name: build-bar
-      watch: demo/bar/main.go
-      workingDir: demo/bar
-    - command: ./demo/bar/bar
-      dependencies: build-bar
-      env:
-        - PORT=9090
-      name: bar
-      ports: "9090"
-    - dependencies: bar
-      name: up
+    - command: go build .
 ```
 
-Start:
+There are several kinds of task:
 
-```bash
-kit up
+A **host task** runs on the host machine. It is defined by a `command`:
+
+```yaml
+- name: build
+  command: go build .
+```
+
+Once a task completes successfully, any downstream tasks are started. If it is unsuccessful, Kit will exit
+
+A task may finish, or run indefinitely. If it runs indefinitely, it is a **service** and  therefore must specify its ports:
+
+```yaml
+- name: service
+  command: go run .
+  ports: [ 8080 ]  
 ```
 
-You'll see something like this:
+Unlike a plain task, if a service fails, it will be restarted. You can specify a `livenessProbe` to determine if the
+service is running correctly:
 
-![screenshot](screenshot.png)
+```yaml
+- name: service
+  command: go run .
+  ports: [ 8080 ]
+  livenessProbe:
+    httpGet:
+      path: /health   
+```
+
+A **shell task** is just a host task that runs in a shell:
+
+```yaml
+- name: shell
+  sh: |
+    set -eux
+    echo "Hello, world!"
+```
 
-Logs are stored in `./logs`.
+A **container task** runs in a container. It is defined by an `image`:
+
+```yaml
+- name: mysql
+  image: mysql
+  ports: [ 3306:3306 ]
+```
+
+If the image is a path to a Dockerfile, it will be built:
+
+```yaml
+- name: kafka
+  image: ./src/images/kafka
+```
+
+A **Kubernetes task** deploys manifests to a Kubernetes cluster:
+
+```yaml
+- name: deploy
+  namespace: default
+  manifests:
+    - manifests/
+    - service.yaml
+  ports: [ 80:8080 ]
+```
+
+Start:
+
+```bash
+kit up
+```
 
 ## Documentation
 

diff --git a/docs/reference/pod-defs-task-properties-namespace.md b/docs/reference/pod-defs-task-properties-namespace.md
@@ -0,0 +1,15 @@
+# Namespace Schema
+
+```txt
+https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/Namespace
+```
+
+The namespace to run the Kubernetes resource in. Defaults to the namespace of the current Kubernetes context.
+
+| Abstract            | Extensible | Status         | Identifiable            | Custom Properties | Additional Properties | Access Restrictions | Defined In                                                            |
+| :------------------ | :--------- | :------------- | :---------------------- | :---------------- | :-------------------- | :------------------ | :-------------------------------------------------------------------- |
+| Can be instantiated | No         | Unknown status | Unknown identifiability | Forbidden         | Allowed               | none                | [pod.schema.json\*](../../out/pod.schema.json "open original schema") |
+
+## Namespace Type
+
+`string` ([Namespace](pod-defs-task-properties-namespace.md))
diff --git a/docs/reference/pod-defs-task.md b/docs/reference/pod-defs-task.md
@@ -28,6 +28,7 @@ A task is a container or a command to run.
 | [args](#args)                       | `array`   | Optional | cannot be null | [Untitled schema](pod-defs-strings.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/args")                                    |
 | [sh](#sh)                           | `string`  | Optional | cannot be null | [Untitled schema](pod-defs-task-properties-sh.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/sh")                           |
 | [manifests](#manifests)             | `array`   | Optional | cannot be null | [Untitled schema](pod-defs-strings.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/manifests")                               |
+| [Namespace](#namespace)             | `string`  | Required | cannot be null | [Untitled schema](pod-defs-task-properties-namespace.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/Namespace")             |
 | [workingDir](#workingdir)           | `string`  | Optional | cannot be null | [Untitled schema](pod-defs-task-properties-workingdir.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/workingDir")           |
 | [user](#user)                       | `string`  | Optional | cannot be null | [Untitled schema](pod-defs-task-properties-user.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/user")                       |
 | [env](#env)                         | `array`   | Optional | cannot be null | [Untitled schema](pod-defs-envvars.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/env")                                     |
@@ -222,6 +223,24 @@ A directories or files of Kubernetes manifests to apply. Once running the task w
 
 `string[]`
 
+## Namespace
+
+The namespace to run the Kubernetes resource in. Defaults to the namespace of the current Kubernetes context.
+
+`Namespace`
+
+*   is required
+
+*   Type: `string` ([Namespace](pod-defs-task-properties-namespace.md))
+
+*   cannot be null
+
+*   defined in: [Untitled schema](pod-defs-task-properties-namespace.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/Namespace")
+
+### Namespace Type
+
+`string` ([Namespace](pod-defs-task-properties-namespace.md))
+
 ## workingDir
 
 The working directory in the container or on the host

diff --git a/docs/reference/pod.md b/docs/reference/pod.md
@@ -741,6 +741,7 @@ Reference this group by using
 | [args](#args)                       | `array`   | Optional | cannot be null | [Untitled schema](pod-defs-strings.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/args")                                    |
 | [sh](#sh)                           | `string`  | Optional | cannot be null | [Untitled schema](pod-defs-task-properties-sh.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/sh")                           |
 | [manifests](#manifests)             | `array`   | Optional | cannot be null | [Untitled schema](pod-defs-strings.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/manifests")                               |
+| [Namespace](#namespace)             | `string`  | Required | cannot be null | [Untitled schema](pod-defs-task-properties-namespace.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/Namespace")             |
 | [workingDir](#workingdir)           | `string`  | Optional | cannot be null | [Untitled schema](pod-defs-task-properties-workingdir.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/workingDir")           |
 | [user](#user)                       | `string`  | Optional | cannot be null | [Untitled schema](pod-defs-task-properties-user.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/user")                       |
 | [env](#env-1)                       | `array`   | Optional | cannot be null | [Untitled schema](pod-defs-envvars.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/env")                                     |
@@ -935,6 +936,24 @@ A directories or files of Kubernetes manifests to apply. Once running the task w
 
 `string[]`
 
+### Namespace
+
+The namespace to run the Kubernetes resource in. Defaults to the namespace of the current Kubernetes context.
+
+`Namespace`
+
+*   is required
+
+*   Type: `string` ([Namespace](pod-defs-task-properties-namespace.md))
+
+*   cannot be null
+
+*   defined in: [Untitled schema](pod-defs-task-properties-namespace.md "https://github.com/kitproj/kit/internal/types/pod#/$defs/Task/properties/Namespace")
+
+#### Namespace Type
+
+`string` ([Namespace](pod-defs-task-properties-namespace.md))
+
 ### workingDir
 
 The working directory in the container or on the host