Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

document tilt improvements #189

Merged
merged 5 commits into from
Mar 14, 2024
Merged

document tilt improvements #189

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c5cf30a
document tilt improvements
saweber Jan 2, 2024
2fd6430
Merge branch 'main' into tilt-improvements
saweber Mar 4, 2024
edd57b3
Update development.md
saweber Mar 5, 2024
82bb538
Update development.md
saweber Mar 5, 2024
8139b74
Merge branch 'main' into tilt-improvements
saweber Mar 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 68 additions & 12 deletions docs/installation/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,19 +20,75 @@ 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 Helm chart.](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 configuration documentation for more).](../configuration)
4. Update `Tiltfile` to allow your remote Kubernetes contexts, if desired. See comment block near top of the `Tiltfile`. [See Tilt 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 Tilt Command Options below.](#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.](#options)
8. Follow instructions in the terminal to open the Tilt UI in browser.
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 an alternative if you wish to store it elsewhere. This file is automatically reloaded in Tilt when updated. Omitted values will use defaults.
Example file:
```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`
- `cloud-integration`
Value: Path to a JSON file for cloud integrations
Optional. Defaults to an empty string.
This is the path to the JSON file to use for the `cloud-integration` secret. [See configuration documentation here.](../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 repository, defaults to an empty string.
Required for a remote cluster, optional for local.
Optional. This is the CPU architecture of the desired node(s) on the cluster.
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).
- `helm-values`
Optional. Defaults to `./tilt-values.yaml`
This is the path to the values.yaml file that will be used for the OpenCost Helm chart.
- `service-key`
Value: Path to a JSON file for a service key
Optional. Defaults to an empty string.
This is the path to the JSON file to use for the `service-key` secret. [See configuration documentation.](../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`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think Prometheus is listening on 80 inside the OpenCost cluster, does this forward 80 to 9080?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct. The only configurable port through tilt is the 'local' side.

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.