\n $\"Slideshow$ \n

\n\nThe browser only talks to this server. Cruise Control credentials stay in the server's environment: they are never sent to the browser, never put in a URL or a request body, and never logged.\n\nWhat you get:\n\n- Pages for cluster state, broker and host load, partition load, Cruise Control state (executor, monitor, analyzer, anomaly detector), proposals, user tasks and a multi-cluster summary.\n- An Admin page for rebalance, preferred leader election, add, remove and demote broker, fix offline replicas, topic replication factor, self-healing and concurrency, sampling and stop execution. Every operation has a separate \"Simulate\" (`dryrun=true`) and \"Execute\" (`dryrun=false`) button, and real executions ask for confirmation.\n- A global panel for asynchronous operations (HTTP 202 and `User-Task-ID`) and a Peer review page for Cruise Control's two-step verification.\n- Light and dark themes, keyboard navigation, tables you can sort and filter, auto-refresh.\n- Login with a local admin or OIDC, roles (viewer, admin), CSRF protection, a strict Content-Security-Policy and an audit log of every POST.\n\n## Quick start\n\n```sh\ndocker run --rm -p 8080:8080 \\\n -e CCUI_AUTH_MODE=none \\\n -e CCUI_CLUSTERS__0__NAME=local \\\n -e CCUI_CLUSTERS__0__URL=http://host.docker.internal:9090/kafkacruisecontrol \\\n ghcr.io/devops-ia/kafka-cruise-control-ui\n```\n\nOpen . `CCUI_AUTH_MODE=none` gives every visitor the admin role and logs a warning at start. Use it only on a laptop. The default mode is `local`, which refuses to start until you set a password hash and a session secret (see [Authentication](#authentication)).\n\nThe image runs as a non-root user, works with `--read-only`, is built `FROM` distroless and declares a healthcheck. `GET /healthz` and `GET /readyz` answer without authentication and expose no configuration.\n\n## Configuration\n\nEverything is configured with environment variables. The server validates all of them at start and exits with a message that names the variable when one is wrong. Unknown `CCUI_*` variables are rejected too, so a typo does not silently turn a security setting off.\n\nSecrets (passwords, tokens, client secrets, the session secret) have no default. Each one can be given directly (`NAME`) or as the path of a file (`NAME_FILE`, trailing newline removed), which is how Kubernetes and Docker secrets are mounted. Secret values are never written to the log.\n\n### Server\n\n| Variable | Required | Default | Example |\n| --- | --- | --- | --- |\n| `CCUI_AUTH_MODE` | no | `local` | `none`, `local` or `oidc` |\n| `CCUI_LISTEN` | no | `:8080` | `127.0.0.1:8080` |\n| `CCUI_TLS_CERT` | no | none | `/tls/tls.crt` (set together with `CCUI_TLS_KEY`) |\n| `CCUI_TLS_KEY` | no | none | `/tls/tls.key` |\n| `CCUI_PUBLIC_URL` | with `oidc` | none | `https://cc.example.com`, the origin users type in the browser |\n| `CCUI_LOGO_URL` | no | built-in mark | `https://cdn.example.com/logo.svg`, the sidebar icon and favicon |\n| `CCUI_SESSION_SECRET` | with `local` and `oidc` | none | 32 or more random characters, see `_FILE` below |\n| `CCUI_SESSION_IDLE_TIMEOUT` | no | `30m` | `15m` |\n| `CCUI_SESSION_MAX_AGE` | no | `12h` | `8h` |\n| `CCUI_COOKIE_INSECURE` | no | `false` | `true` only for plain-HTTP development |\n| `CCUI_LOGIN_MAX_ATTEMPTS` | no | `5` | `10` |\n| `CCUI_LOGIN_WINDOW` | no | `15m` | `10m` |\n| `CCUI_TRUST_XFF` | no | `false` | `true` behind a reverse proxy that appends the client address |\n| `CCUI_MAX_BODY_BYTES` | no | `1048576` | `65536` |\n\n### Local users (`CCUI_AUTH_MODE=local`)\n\nDefine one or more users with consecutive indexes from 0, or only the admin shortcut. At least one user is required. Names must be unique, also against the shortcut and against OIDC user names.\n\n| Variable | Required | Default | Example |\n| --- | --- | --- | --- |\n| `CCUI_LOCAL_USERS____NAME` | yes, per user | none | `ana` |\n| `CCUI_LOCAL_USERS____PASSWORD_HASH` | yes, per user | none | a bcrypt or argon2id hash; plain text is rejected |\n| `CCUI_LOCAL_USERS____ROLE` | yes, per user | none | `viewer` or `admin` |\n| `CCUI_LOCAL_ADMIN_USER` | no | `admin` | `ops` |\n| `CCUI_LOCAL_ADMIN_PASSWORD_HASH` | no | none | shortcut for one admin user |\n\n### Clusters\n\nClusters are numbered from 0 with no gaps. `` is the index.\n\n| Variable | Required | Default | Example |\n| --- | --- | --- | --- |\n| `CCUI_CLUSTERS____NAME` | yes | none | `prod-eu`, letters, digits, `.`, `_`, `-`; unique |\n| `CCUI_CLUSTERS____URL` | yes | none | `http://cc.kafka:9090/kafkacruisecontrol` |\n| `CCUI_CLUSTERS____GROUP` | no | none | `prod`, groups clusters in the selector |\n| `CCUI_CLUSTERS____TIMEOUT` | no | `60s` | `120s`, per request |\n| `CCUI_CLUSTERS____AUTH_TYPE` | no | `none` | `none`, `basic`, `bearer`, `sigv4` or `oidc` |\n| `CCUI_CLUSTERS____AUTH_USER` | with `basic` | none | `svc-ccui` |\n| `CCUI_CLUSTERS____AUTH_PASSWORD` | with `basic` | none | |\n| `CCUI_CLUSTERS____AUTH_TOKEN` | with `bearer` | none | |\n| `CCUI_CLUSTERS____AUTH_SIGV4_REGION` | with `sigv4` | none | `eu-west-1` |\n| `CCUI_CLUSTERS____AUTH_SIGV4_SERVICE` | no | `execute-api` | `execute-api` |\n| `CCUI_CLUSTERS____AUTH_OIDC_TOKEN_URL` | with `oidc` | none | `https://auth.example.com/oauth2/token` |\n| `CCUI_CLUSTERS____AUTH_OIDC_CLIENT_ID` | with `oidc` | none | |\n| `CCUI_CLUSTERS____AUTH_OIDC_CLIENT_SECRET` | with `oidc` | none | |\n| `CCUI_CLUSTERS____AUTH_OIDC_SCOPE` | no | none | `cruise-control/admin` |\n| `CCUI_CLUSTERS____AUTH_FORWARD_IDENTITY` | no | none (off) | `jwt` or `doas` |\n\n### OIDC login (`CCUI_AUTH_MODE=oidc`)\n\nOne or more providers, numbered from 0. Any OpenID Connect provider that publishes discovery metadata works (Microsoft Entra ID, Google, Amazon Cognito, Keycloak, Dex and similar). The login uses the authorization code flow with PKCE, `state` and `nonce`. The redirect URL to register at the provider is `/api/auth//callback`.\n\n| Variable | Required | Default | Example |\n| --- | --- | --- | --- |\n| `CCUI_OIDC____NAME` | yes | none | `corp`, lowercase letters, digits and `-`; shown on the button |\n| `CCUI_OIDC____ISSUER` | yes | none | `https://login.microsoftonline.com//v2.0` |\n| `CCUI_OIDC____CLIENT_ID` | yes | none | |\n| `CCUI_OIDC____CLIENT_SECRET` | yes | none | |\n| `CCUI_OIDC____REDIRECT_URL` | no | `/api/auth//callback` | |\n| `CCUI_OIDC____SCOPES` | no | `openid profile email` | `openid profile email groups` |\n| `CCUI_OIDC____GROUPS_CLAIM` | no | `groups` | `roles` |\n| `CCUI_OIDC____ADMIN_GROUPS` | no | none | `ccui-admins,platform` |\n| `CCUI_OIDC____VIEWER_GROUPS` | no | none | `developers` |\n| `CCUI_OIDC____DEFAULT_ROLE` | no | none (access denied) | `viewer` |\n\nEvery secret above also accepts the `_FILE` form, for example `CCUI_SESSION_SECRET_FILE`, `CCUI_LOCAL_ADMIN_PASSWORD_HASH_FILE`, `CCUI_LOCAL_USERS__0__PASSWORD_HASH_FILE`, `CCUI_CLUSTERS__0__AUTH_PASSWORD_FILE`, `CCUI_CLUSTERS__0__AUTH_TOKEN_FILE`, `CCUI_CLUSTERS__0__AUTH_OIDC_CLIENT_SECRET_FILE` and `CCUI_OIDC__0__CLIENT_SECRET_FILE`.\n\nGitHub is an OAuth provider without OIDC discovery and is not supported directly. Put an OIDC broker such as Dex or Keycloak in front of it.\n\n## Authentication\n\n| Mode | What it does |\n| --- | --- |\n| `none` | No login. Everyone is `admin`. A warning is logged at start. |\n| `local` | One admin account checked against a bcrypt or argon2id hash. |\n| `oidc` | Users sign in at an OpenID Connect provider. Their role comes from a groups claim. |\n\nMake a bcrypt hash for a local user (the leading `:` and the newline are removed):\n\n```sh\nhtpasswd -bnBC 12 \"\" 'your password' | tr -d ':\\n'\n```\n\nExample, one cluster with a local admin. The hash below is for a random password that nobody knows; replace it.\n\n```env\nCCUI_AUTH_MODE=local\nCCUI_SESSION_SECRET=replace-with-at-least-32-random-characters\nCCUI_LOCAL_ADMIN_PASSWORD_HASH=$2a$10$jDy/91QpAa9CaSz6CQ1YX.uzTI0uNvUjh0c6H2P.2w8Zqa1433ism\nCCUI_CLUSTERS__0__NAME=prod\nCCUI_CLUSTERS__0__URL=http://cc.kafka.svc:9090/kafkacruisecontrol\n```\n\nSessions are kept in memory with a random 256-bit id in an `HttpOnly`, `Secure`, `SameSite=Lax` cookie. They end on logout, after the idle timeout and after the maximum age. They are lost when the process restarts, and with more than one replica you need session affinity at the ingress.\n\nFailed logins are limited per client address and per user name. After `CCUI_LOGIN_MAX_ATTEMPTS` failures inside `CCUI_LOGIN_WINDOW` the login answers 429 with `Retry-After`, even for the right password. Behind a reverse proxy set `CCUI_TRUST_XFF=true`, otherwise every user shares the proxy's address.\n\nState-changing requests need a CSRF token (from `GET /api/session`, sent as `X-CSRF-Token`) and an `Origin` equal to the server's own origin. Set `CCUI_PUBLIC_URL` when a proxy changes the `Host` header.\n\n## Roles\n\n| Role | Can |\n| --- | --- |\n| `viewer` | Overview and Load pages only: the endpoints `kafka_cluster_state`, `state`, `load`, `partition_load` and `permissions`. Anything else answers 403. |\n| `admin` | Everything: proposals, user tasks, peer review, dry-runs, executions, `admin`, `review`, `topic_configuration`, pause and resume sampling, stop execution. |\n\nEach local user has the role set in `CCUI_LOCAL_USERS____ROLE`; the `CCUI_LOCAL_ADMIN_*` shortcut and everyone in `none` mode are `admin`. With OIDC, `admin` wins over `viewer` when both group lists match; a user who matches none gets `DEFAULT_ROLE`, or is refused when it is not set.\n\n## Talking to Cruise Control\n\nThe server calls only the Cruise Control 3.x endpoints it knows (the table lives in `internal/proxy/table.go` and a test compares it with Cruise Control's own endpoint definitions). The upstream URL comes only from the configuration, so a client cannot make the server call anything else. `json=true` is always added, `dryrun` must be explicit on POSTs, and parameters Cruise Control does not declare for an endpoint are rejected with 400. Nothing from the browser (cookies, `Authorization`, other headers) reaches Cruise Control, and `Set-Cookie`, `WWW-Authenticate` and `Location` from Cruise Control never reach the browser.\n\n| `AUTH_TYPE` | Request to Cruise Control |\n| --- | --- |\n| `none` | no `Authorization` header |\n| `basic` | `Authorization: Basic ...` |\n| `bearer` | `Authorization: Bearer ` |\n| `sigv4` | signed with AWS Signature V4 using the default AWS credential chain (environment, shared config, IRSA, instance role) |\n| `oidc` | `Authorization: Bearer ` from the OAuth2 client-credentials grant, cached until it expires |\n\n`AUTH_FORWARD_IDENTITY` is off by default. `jwt` sends the user's own OIDC id token as the Bearer token instead of the service credentials (it needs `CCUI_AUTH_MODE=oidc`). `doas` keeps the service credentials and adds `doAs=`.\n\nCruise Control's own security must be on for per-user identities to mean anything. If the sampler setting of your Cruise Control leaves the load pages empty, check its metric sampler configuration; the UI only shows what Cruise Control reports.\n\nGoals in the Admin forms are read from the analyzer state of the selected cluster. Cruise Control does not say which goals are hard, so the UI groups names containing `CapacityGoal`, `RackAware`, `BrokerSetAware` or `MinTopicLeadersPerBroker` as hard and everything else as soft. A goal the UI has never seen still appears, under soft.\n\n### Two clusters\n\n```env\nCCUI_AUTH_MODE=none\nCCUI_CLUSTERS__0__NAME=prod-eu\nCCUI_CLUSTERS__0__GROUP=prod\nCCUI_CLUSTERS__0__URL=http://cc-eu.kafka.svc:9090/kafkacruisecontrol\nCCUI_CLUSTERS__0__AUTH_TYPE=basic\nCCUI_CLUSTERS__0__AUTH_USER=ccui\nCCUI_CLUSTERS__0__AUTH_PASSWORD=replace-me\nCCUI_CLUSTERS__1__NAME=staging\nCCUI_CLUSTERS__1__GROUP=dev\nCCUI_CLUSTERS__1__URL=http://cc-staging.kafka.svc:9090/kafkacruisecontrol\nCCUI_CLUSTERS__1__TIMEOUT=120s\n```\n\n## Security notes\n\n- Responses carry a Content-Security-Policy with a per-response nonce and no `unsafe-inline`, `frame-ancestors 'none'`, `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, `Referrer-Policy` and `Permissions-Policy`. `Strict-Transport-Security` is sent only when this process serves TLS itself (`CCUI_TLS_CERT` and `CCUI_TLS_KEY`, TLS 1.2 or newer).\n- Every POST to Cruise Control writes one JSON audit line to stdout with the user, role, cluster, endpoint, parameters and result status, also for refused attempts. Cookies, `Authorization` and tokens are never recorded.\n- Request bodies are capped (`CCUI_MAX_BODY_BYTES`), every upstream call has a timeout, and a Cruise Control that is down or slow becomes a 502 or 504 with a generic message.\n\n## Development\n\nYou need Go `1.26` or newer and `Node 22` or newer.\n\n```sh\ncd web && npm ci && npm run build && cd .. # builds the SPA into web/dist, which the binary embeds\ngo test ./...\ngo vet ./...\nCCUI_AUTH_MODE=none CCUI_CLUSTERS__0__NAME=local CCUI_CLUSTERS__0__URL=http://localhost:9090/kafkacruisecontrol go run ./cmd/server\n```\n\nFor SPA work, `cd web && npm run dev` starts Vite on port 5173 and proxies `/api` to a server on port 8080. `npm run typecheck` and `npm test` run the type checks and the unit tests.\n\n`docker build -t kafka-cruise-control-ui .` runs the same three stages as CI: Node builds the SPA, Go builds the binary with the SPA embedded, and the result is copied into a distroless non-root image. The sidebar shows `dev` as the version unless you pass one, for example `--build-arg VERSION=v1.4.0`; CI passes the release tag.\n\nThe frozen LinkedIn UI can still be built locally with `docker build --target legacy`; see [Legacy UI](docs/DEPLOYMENT.md#legacy-ui).\n\n## License\n\nSee [LICENSE](LICENSE).\n","has_starred","hub_user","immutable_tags_settings",{"_226":11,"_227":228},"enabled","rules",[229],".*","is_automated","permissions",{"_233":22,"_234":11,"_235":11},"read","write","admin","user","storage_size",117364055,"isOrg","reponame","tag","sha256:255f0b460a6fc5577484dc53c00a906da056dc0bbd414fc8d5221709606a11f5","canDeleteTags","isHubSbxKitsEnabled","currentTab","tagAttestations","displaySecurityMetadata","showSbxLogoOverride","showSbxAgenticPlatformBadge","routes/_layout.layers.$namespace.$reponame.$tag.(images).($imageUrlDigest)._index",{"_27":28,"_189":-7,"_187":-7,"_188":-7,"_29":252,"_35":242,"_256":-7,"_257":11},{"_31":32,"_33":34,"_35":36,"_37":38,"_39":40,"_41":253,"_67":68,"_69":34,"_70":71,"_72":73,"_74":75,"_76":77,"_78":50,"_79":68,"_80":59,"_81":22},[254,255],{"_44":45,"_35":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":48,"_56":-5,"_57":38,"_58":59,"_60":-5},{"_44":62,"_35":63,"_47":48,"_49":64,"_51":65,"_53":54,"_55":48,"_56":-5,"_57":66,"_58":59,"_60":-5},"imageWithLayers","hasPermissionToViewRepoSettings","actionData","errors"]

devopsiaci/kafka-cruise-control-ui:latest