From 79d5eff6e8bca42b98014dadbab0db73ef1d3549 Mon Sep 17 00:00:00 2001 From: Steven Date: Tue, 2 Jan 2024 11:22:07 -0700 Subject: [PATCH] document tilt improvements Signed-off-by: Steven --- docs/installation/development.md | 78 ++++++++++++++++++++++++++------ 1 file changed, 65 insertions(+), 13 deletions(-) diff --git a/docs/installation/development.md b/docs/installation/development.md index 59a7084..877e600 100644 --- 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. \ No newline at end of file