Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
60 changes: 3 additions & 57 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,63 +27,9 @@ kubectl apply -k deployment/overlays/openshift

This deploys to the `openshift-tuning` namespace.

For detailed installation instructions, see the [Installation Guide](docs/installation.md).

## Running the application in dev mode
## Documentation

You can run your application in dev mode that enables live coding using:
For detailed documentation, see the [docs/](docs/README.md) directory covering installation, configuration, API reference, architecture, and contributing guidelines.

```shell script
./mvnw quarkus:dev
```


## Packaging and running the application

The application can be packaged using:

```shell script
./mvnw package
```

It produces the `quarkus-run.jar` file in the `target/quarkus-app/` directory.
Be aware that it’s not an _über-jar_ as the dependencies are copied into the `target/quarkus-app/lib/` directory.

The application is now runnable using `java -jar target/quarkus-app/quarkus-run.jar`.

If you want to build an _über-jar_, execute the following command:

```shell script
./mvnw package -Dquarkus.package.jar.type=uber-jar
```

The application, packaged as an _über-jar_, is now runnable using `java -jar target/*-runner.jar`.

## Creating a native executable

You can create a native executable using:

```shell script
./mvnw package -Dnative
```

Or, if you don't have GraalVM installed, you can run the native executable build in a container using:

```shell script
./mvnw package -Dnative -Dquarkus.native.container-build=true
```

You can then execute your native executable with: `./target/kruize-optimizer-1.0.0-SNAPSHOT-runner`

If you want to learn more about building native executables, please consult <https://quarkus.io/guides/maven-tooling>.

## Related Guides

- Scheduler ([guide](https://quarkus.io/guides/scheduler)): Schedule jobs and tasks
- REST Qute ([guide](https://quarkus.io/guides/qute-reference#rest_integration)): Qute integration for Quarkus REST. This extension is not compatible with the quarkus-resteasy extension, or any of the extensions that depend on it.
- REST ([guide](https://quarkus.io/guides/rest)): A Jakarta REST implementation utilizing build time processing and Vert.x. This extension is not compatible with the quarkus-resteasy extension, or any of the extensions that depend on it.
- REST Jackson ([guide](https://quarkus.io/guides/rest#json-serialisation)): Jackson serialization support for Quarkus REST. This extension is not compatible with the quarkus-resteasy extension, or any of the extensions that depend on it
- SmallRye OpenAPI ([guide](https://quarkus.io/guides/openapi-swaggerui)): Document your REST APIs with OpenAPI - comes with Swagger UI
- Kubernetes Client ([guide](https://quarkus.io/guides/kubernetes-client)): Interact with Kubernetes and develop Kubernetes Operators
- Logging JSON ([guide](https://quarkus.io/guides/logging#json-logging)): Add JSON formatter for console logging
- YAML Configuration ([guide](https://quarkus.io/guides/config-yaml)): Use YAML to configure your Quarkus application
- Micrometer Registry Prometheus ([guide](https://quarkus.io/guides/micrometer)): Enable Prometheus support for Micrometer
24 changes: 24 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Kruize Optimizer Documentation

Welcome to the Kruize Optimizer documentation! This guide will help you understand, install, configure, and contribute to the Kruize Optimizer project.

## Documentation

| # | Guide | Description |
|---|-------|-------------|
| 1 | [Installation Guide](installation.md) | Install and deploy Kruize Optimizer |
| 2 | [Configuration Guide](configurables.md) | Configure and customize your deployment |
| 3 | [API Reference](optimizerAPI.md) | Optimizer API endpoints and examples |
| 4 | [Design Documentation](design.md) | Architecture and system workflows |
| 5 | [Build Guide](build.md) | Build and push Docker images |
| 6 | [Contributing Guide](contributing.md) | How to contribute to the project |

## Additional Resources

- [Main README](../README.md) - Project overview and quick start
- [Kruize Design Docs](https://github.com/kruize/autotune/tree/master/design) - Kruize product documentation
- [Kruize Operator](https://github.com/kruize/kruize-operator/) - Kruize Operator

---

**Last Updated**: 2026-11-04
86 changes: 86 additions & 0 deletions docs/build.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# Build Guide

This guide explains how to build and push Docker images for Kruize Optimizer.

## Table of Contents

- [Overview](#overview)
- [Build Script](#build-script)
- [Build Options](#build-options)

## Overview

Kruize Optimizer provides a convenient build script ([`build_and_push.sh`](../build_and_push.sh)) that simplifies building and pushing Docker images. The script uses Quarkus Jib extension for efficient container image creation.

## Build Script

### Basic Usage

```bash
./build_and_push.sh [OPTIONS]
```

### Script Options

| Option | Description | Default |
|--------|-------------|---------|
| `-i IMAGE_NAME` | Full image name (registry/repository:tag) | quay.io/kruize/optimizer:0.1 |
| `-t TAG` | Image tag (used if -i not provided) | 0.1 |
| `-b BUILD` | Build image (true/false) | true |
| `-p PUSH` | Push image (true/false) | true |
| `-l PLATFORMS` | Target platforms | linux/amd64,linux/arm64 |
| `-h` | Show help message | - |

**Note**: Use either `-i` for full image name OR `-t` for tag with default registry/repo.

## Build Options

### 1. Build Only (No Push)

Build the image locally without pushing to a registry:

```bash
./build_and_push.sh -p false
```

### 2. Build and Push with Custom Tag

Build and push with a specific tag (run `docker login <registry-url>` first):

```bash
./build_and_push.sh -t 1.0.0
```

This creates: `quay.io/kruize/optimizer:1.0.0`

### 3. Build and Push with Full Image Name

Specify the complete image name including registry:

```bash
./build_and_push.sh -i quay.io/myuser/kruize-optimizer:1.0.0
```

### 4. Build for Specific Platform

Build for a single platform (faster):

```bash
./build_and_push.sh -l linux/amd64 -p false
```

### 5. Multi-Platform Build

Build for multiple platforms (default):

```bash
./build_and_push.sh -l linux/amd64,linux/arm64
```

For more options, run `./build_and_push.sh -h`.

---

**Previous**: [Design Documentation](design.md) | **Next**: [Contributing Guide](contributing.md) | [Back to docs](README.md)

**Last Updated**: 2026-11-04
128 changes: 128 additions & 0 deletions docs/configurables.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# Configuration Guide

This guide describes all configurable options available in Kruize Optimizer and how to customize them for your environment.

## Table of Contents

- [Overview](#overview)
- [Application Configuration](#application-configuration)
- [Profile Configuration](#profile-configuration)
- [Bulk Config Configuration](#bulk-config-configuration)
- [Environment Variables](#environment-variables)

## Overview

Kruize Optimizer uses a combination of configuration files, environment variables, and runtime profiles to provide flexible customization options. Configuration can be modified at different levels:

1. **Application Level**: Core application settings
2. **Profile Level**: Metadata and metric profiles

## Application Configuration

### Main Configuration File

The primary configuration file is located at [`src/main/resources/application.yml`](../src/main/resources/application.yml).

#### Key Configuration Sections

```yaml
# HTTP Server Configuration
quarkus:
application:
name: kruize-optimizer-service
version: 1.0.0

# OpenAPI Configuration
smallrye-openapi:
path: /openapi

# Swagger UI Configuration
swagger-ui:
path: /swagger-ui
always-include: ${ENABLE_SWAGGER:false}

# Logging Configuration
log:
console:
json:
enabled: false
pretty-print: false

# REST Client Configuration
rest-client:
"com.kruize.optimizer.client.KruizeClient":
url: ${kruize.url}

# Kruize Optimizer Configuration
kruize:
# URL of the Kruize Autotune service
url: ${KRUIZE_URL:http://kruize:8080}

# Startup initialization (set to false to skip auto-initialization)
startup:
initialize: true

state:
refresh:
# Interval to refresh state and install missing profiles
interval: ${KRUIZE_STATE_REFRESH_INTERVAL:60m}

webhook:
# Webhook URL for bulk API callbacks
url: ${KRUIZE_WEBHOOK_URL:http://kruize-optimizer:8080/webhook}

defaults:
# Default datasource name
datasource: ${KRUIZE_DEFAULT_DATASOURCE:prometheus-1}
# Default metadata profile name
metadata-profile: ${KRUIZE_DEFAULT_METADATA_PROFILE:cluster-metadata-local-monitoring}
# Default metric profile name
metric-profile: ${KRUIZE_DEFAULT_METRIC_PROFILE:resource-optimization-local-monitoring}
```

## Profile Configuration

The Optimizer bundles default metadata and metric profiles that are automatically installed into Kruize on startup if missing.

- **Metadata Profiles**: `src/main/resources/configs/v1.0/metadata-profiles/`
- **Metric Profiles**: `src/main/resources/configs/v1.0/metric-profiles/`

For profile schema and design details, refer to the [Kruize Autotune documentation](https://github.com/kruize/autotune/tree/master/design).


## Bulk Config Configuration

Bulk job scheduling is **config-driven**. Each `BulkConfig` object stored in Kruize defines its own scheduling interval, target namespaces, labels, and experiment settings. The Optimizer fetches enabled configs on startup and schedules per-config timers automatically.

For bulk config fields, API details, and usage, refer to the [Kruize Autotune documentation](https://github.com/kruize/autotune/tree/master/design).

## Environment Variables

### Core Quarkus Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `QUARKUS_HTTP_PORT` | 8080 | HTTP server port |
| `QUARKUS_HTTP_HOST` | 0.0.0.0 | HTTP bind address |
| `QUARKUS_LOG_LEVEL` | INFO | Logging level (TRACE, DEBUG, INFO, WARN, ERROR) |
| `ENABLE_SWAGGER` | false | Enable Swagger UI |

### Kruize Optimizer Environment Variables

All environment variables used in Kruize Optimizer deployment:

| Variable | Default | Description |
|----------|---------|-------------|
| `KRUIZE_URL` | http://kruize:8080 | URL of the Kruize Autotune service |
| `KRUIZE_STARTUP_INITIALIZE` | true | Enable/disable automatic initialization on startup |
| `KRUIZE_STATE_REFRESH_INTERVAL` | 60m | Interval to refresh state and install missing profiles |
| `KRUIZE_WEBHOOK_URL` | http://kruize-optimizer:8080/webhook | Webhook URL for bulk API callbacks |
| `KRUIZE_DEFAULT_DATASOURCE` | prometheus-1 | Default datasource name |
| `KRUIZE_DEFAULT_METADATA_PROFILE` | cluster-metadata-local-monitoring | Default metadata profile name |
| `KRUIZE_DEFAULT_METRIC_PROFILE` | resource-optimization-local-monitoring | Default metric profile name |

---

**Previous**: [Installation Guide](installation.md) | **Next**: [API Reference](optimizerAPI.md) | [Back to docs](README.md)

**Last Updated**: 2026-11-04
53 changes: 53 additions & 0 deletions docs/contributing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Contributing to Kruize Optimizer

Thank you for your interest in Kruize Optimizer! We welcome your contributions to the project.

## Contribution Workflow

These steps outline the general contribution workflow:

- Fork and set up the Kruize Optimizer repository on your workstation
- Create a topic branch from where you want to base your work (usually main)
- Install the required software to build and deploy (see [Installation Guide](installation.md))
- Make sure the tests pass, add any new tests if appropriate
- Make commits of logical units
- Make sure your commit messages are in the proper format (see [below](#commit-message))
- Push your changes to a topic branch in your fork of the repository
- Submit a pull request to the original repository
- Ensure the PR checks pass

### Fork and Clone

```bash
git clone https://github.com/YOUR_USERNAME/kruize-optimizer.git
cd kruize-optimizer
git remote add upstream https://github.com/kruize/kruize-optimizer.git
```

### Running Tests

```bash
# Run all tests
./mvnw test

# Run with coverage
./mvnw verify
```

## Commit Message

We use GPG keys for signing the commits. Refer [generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) for details. The commit message should indicate what has changed and why the change was made. Sign off on your commit in the footer. By doing this, you assert original authorship of the commit and that you are permitted to contribute it. This can be automatically added to your commit by passing `-S` to `git commit`, or by manually adding the following line to the footer of the commit.

```
Signed-off-by: Full Name <email>
```

## License

By contributing, you agree that your contributions will be licensed under the same license as the project.

---

**Previous**: [Build Guide](build.md) | [Back to docs](README.md)

**Last Updated**: 2026-11-04
Loading
Loading