document tilt improvements

Signed-off-by: Steven <[email protected]>
opencost · Jan 2, 2024 · 79d5eff · 79d5eff
1 parent 1138bbf
commit 79d5eff
Showing 1 changed file with 65 additions and 13 deletions.
diff --git a/docs/installation/development.md b/docs/installation/development.md
@@ -20,19 +20,71 @@ Tilt is a great way to run OpenCost on a local or remote Kubernetes environment.
 
 ## Run OpenCost
 1. In a terminal, run: `helm repo add prometheus-community https://prometheus-community.github.io/helm-charts`
-2. Update `tilt-values.yaml` to desired attributes - [see documentation here.](https://github.com/opencost/opencost-helm-chart/blob/main/charts/opencost/README.md)
-3. Update `Tiltfile` to allow your remote Kubernetes contexts, if desired. See comment block near top of the `Tiltfile`. [See documentation here.](https://docs.tilt.dev/api#api.allow_k8s_contexts)
-4. If using `kind`, in a terminal, run `kind create cluster` to create local cluster, or set your Kubernetes context to the desired cluster.
-5. In a terminal, run `tilt up -- --arch [amd64 or arm64] --docker-repo [repo or username]` at the root of the OpenCost repository
-        `--arch amd64` will compile OpenCost for amd64 nodes, `--arch arm64` will compile for arm64 nodes
-        `--docker_repo` is only required for remote development, or you want the images saved in Docker Hub. The value is prepended to the image tag (the -t flag in a Docker build command). [See Docker Documentation](https://docs.docker.com/engine/reference/commandline/build/#tag).
-        Example: `tilt up -- --arch amd64 --docker-repo example` would build OpenCost for a Kubernetes node with an `amd64` architecture, and push the images to the Docker Hub user `example`.
-6. Follow instructions to open the Tilt UI in browser (hit space, or navigate to http://localhost:10350)
-7. As you update your code or `tilt-values.yaml`, Tilt will automatically watch relevant source code and recompile, build, deploy, and run tests.
-8. `tilt down` will tear down resources created, otherwise they will continue to run indefinitely.
-9. `kind delete` cluster will delete the local cluster, if desired.
+2. Update `tilt-values.yaml` or create a new yaml file to contain desired attributes - [see documentation here.](https://github.com/opencost/opencost-helm-chart/blob/main/charts/opencost/README.md)
+3. Optional - configure JSON files for cloud integration(s) and a service key [(see here).](..#configuration#configuration)
+4. Update `Tiltfile` to allow your remote Kubernetes contexts, if desired. See comment block near top of the `Tiltfile`. [See documentation here.](https://docs.tilt.dev/api#api.allow_k8s_contexts)
+5. If using `kind`, in a terminal, run `kind create cluster` to create local cluster, or set your Kubernetes context to the desired cluster.
+6. Configure a `tilt_config.json` file - (see below section)[##tilt-command-options]
+7. In a terminal, run `tilt up` at the root of the OpenCost repository. See [Tilt Command Options below for more options.](#tilt-command-options)
+8. Follow instructions to open the Tilt UI in browser (hit space, or navigate to http://localhost:10350)
+9. As you update code, `tilt_config.json`, or `tilt-values.yaml`, Tilt will automatically watch relevant source code and recompile, build, deploy, and run tests.
+10. `tilt down` will tear down resources created, otherwise they will continue to run indefinitely.
+11. `kind delete` cluster will delete the local cluster, if desired.
+
+## Tilt Command Options
+
+### via `tilt_config.json`
+The best way to configure OpenCost to use tilt is with a `tilt_config.json` file in the root of the OpenCost repository. The file must live there; a symlink is thebest alternative if you wish to store it elsewhere. This file is automatically reloaded in tilt when updated. Omitted values will use defaults. Example contents:
+```JSON
+{
+  "arch":"amd64",
+  "cloud-integration":"../cloud-integration.json"
+}
+```
+
+### via CLI
+These options can also be placed after `tilt up --`. Example command:
+`tilt up -- --arch arm64 --docker-repo dockerhub-username --cloud-integration ../cloud-integration.json --service-key ../service-key.json`
+Options defined from the CLI will override those from `tilt_config.json`.
+
+### Options
+- `arch`
+  Value: `amd64`(default),`arm64`
+  Optional. This is the CPU architecture of the cluster nodes used.
+  The value is prepended to the docker image names (the -t flag in a Docker build command). [See Docker Documentation](https://docs.docker.com/engine/reference/commandline/build/#tag).
+- `cloud-integration`
+  Value: `path_to_cloud_integration_json_file`
+  Optional. Defaults to an empty string.
+  This is the path to the JSON file to use for the `cloud-integration` secret. (See here for more.)[#..#configuration#configuration]
+- `delve-continue`
+  Value: `true`(default) or `false`
+  Optional, defaults to true. Determines if the `--continue` flag is used with delve. By default, this will let applications start without a debugger attached. `false` will wait for a debugger to attach before starting.
+- `docker-repo` 
+  Value: `docker_hub_username or docker_repository`
+  Required for a remote cluster, optional for local. 
+- `helm-values`
+  Optional. Defaults to `./tilt-values.yaml`
+  This it he path to the values.yaml file that will be used for the OpenCost helm chart.
+- `service-key path_to_service_key_json_file`
+  Optional. Defaults to an empty string.
+  This is the path to the JSON file to use for the `service-key` secret. (See here for more.)[#..#configuration#configuration]
+- `port-costmodel`
+  Optional. Defaults to 9003.
+  This is the port forwarded to localhost for the costmodel (back end).
+  Note: In `tilt_config.json`, this is a string and must be in quotes, since Tilt options must be a bool or a string.
+- `port-debug`
+  Optional. Defaults to 40000.
+  This is the port forwarded to localhost for delve.
+  Note: In `tilt_config.json`, this is a string and must be in quotes, since Tilt options must be a bool or a string.
+- `port-prometheus`
+  Optional. Defaults to 9080.
+  This is the port forwarded to localhost for Prometheus.
+  Note: In `tilt_config.json`, this is a string and must be in quotes, since Tilt options must be a bool or a string.
+- `port-ui`
+  Optional. Defaults to 9090.
+  This is the port forwarded to localhost for the web UI.
+  Note: In `tilt_config.json`, this is a string and must be in quotes, since Tilt options must be a bool or a string.
 
 ## Attach Debugger to the Back End
-The OpenCost back end auto starts with delve by default. Configure your IDE or text editor to attach to `http://localhost:40000`.
+The OpenCost back end auto starts with delve by default. Configure your IDE or text editor to attach to `http://localhost:40000` (or specified value of the `port-debug` option).
 
-If you want to attach the debugger at startup, remove the `--continue` flag from the entrypoint in the `docker_build_with_restart` function in the `Tiltfile`, then connect the debugger. Once connected, the OpenCost back end will start.