|
Important
|
This project is still experimental, feel free to share feedback |
Udash is an Updatecli backend application. Its mission is to visualize Updatecli pipeline report and to provide various insights such as Git repositories "update" state.
Pipeline Report
Updatecli can be configured to upload pipeline reports after each execution. The goal is to have a central place to visualize all pipelines for a specific project.
Insight
Insight reuse pipeline report to provide a visualization per theme such as the state for all dependencies for a specific git repository.
Still work in progress
The best way to discover Udash is to try it yourself. There is a docker compose example available in the demo directory.
Deploy Udash with the following steps:
-
Make sure you have Docker and Docker Compose installed.
-
Run
docker compose up -din the directorydemo. -
Configure your browser to access Udash at
http://localhost. Traefik serves the frontend on port 80 and the API onhttp://localhost/api, its own dashboard is the one on port 8080. -
Run
updatecli udash login "http://localhost" --experimentalto configure Updatecli to upload reports to Udash. -
Then you can run any updatecli command (apply/diff) to start publishing reports to Udash
The demo runs with authentication disabled. Because no OAuth flag is passed, udash login skips the
authorization flow and simply records the endpoint in the Updatecli configuration file.
Please be aware that the UI is designed to visualize pipelines per git repository, so without an
scmid pipelines will be hard to discover.
INFO: You may have to run docker compose restart server if the postgresql database
wasn’t ready in time to receive connections when the Udash server started.
Don’t worry if you don’t have any Updatecli manifest yet, you can still try the demo by using the Updatecli policies used by this Git repository. For that you need Updatecli and GitHub access token to interact with the GitHub API.
You can run the following commands to configure Updatecli to use the policies defined in this repository:
-
export GITHUB_TOKEN=<your-github-token> -
export GITHUB_ACTOR=<your-github-username> -
docker login ghcr.ioto authenticate on the GitHub Container Registry for pullling Updatecli policies -
updatecli compose diff --experimentalto execute Updatecli policies defined in the fileupdatecli-compose.yaml
Udash requires a postgresql database to store the various pipeline reports. An oauth provider is only required when authentication is enabled, which it is not by default.
Postgresql Database
OAuth provider
The oauth provider must allow the PKCE flow.
-
Zitadel (the reference deployment, and the provider behind the dedicated
zitadelmode) -
Auth0 (tested)
-
GitHub Not supported yet
Udash must be configured via a configuration file, and some settings can be overridden by environment variables
Config File
The configuration file is named config.yaml and is looked up, in order, in the working directory,
then $HOME/.udash/, then /etc/udash/. The first one found wins. A different name can be passed
with --config.
server:
auth:
# mode selects the authentication backend.
# Accepted values are "oauth", "zitadel", and "none".
# Unset or "none" disables authentication entirely.
mode: "oauth"
# visibility controls which endpoints require a token.
# "public" (the default) leaves the read endpoints open and requires
# authentication for anything that writes.
# "private" requires authentication everywhere.
visibility: "public"
# oauth settings, used when mode is "oauth"
oauth:
# issuer is compared to the "iss" claim of the token, verbatim.
# A scheme is optional, https is assumed when it is omitted, but the
# trailing slash is significant: Auth0 issues one, Zitadel and Keycloak
# do not. A mismatch rejects every token.
issuer: "https://example.eu.auth0.com/"
# audience is a list, and every entry is accepted.
audience:
- "https://udash.example/api"
# zitadel settings, used when mode is "zitadel"
zitadel:
domain: "xxx.region.zitadel.cloud"
# keyfile is the path to a service account key file
keyfile: "/etc/udash/zitadel-key.json"
# role required to access the API. Empty means any authenticated user.
role: ""
database:
# uri defines the postgresql URI used to connect with its database
uri: "postgres://udash:password@db:5432/udash?sslmode=disable"
# migrationdisabled skips the schema migrations run at startup
migrationdisabled: falseEnvironment
Each variable below is only a fallback: it is read when the matching key is absent from the configuration file, so the file always wins.
-
UDASH_AUTH_MODE: Authentication mode. Accepted values are ["", "none", "oauth", "zitadel"]
-
UDASH_AUTH_OAUTH_ISSUER: Oauth issuer URL, requires
UDASH_AUTH_MODEset to "oauth" -
UDASH_AUTH_OAUTH_AUDIENCE: Oauth audience, requires
UDASH_AUTH_MODEset to "oauth" -
UDASH_AUTH_ZITADEL_DOMAIN: Zitadel domain, requires
UDASH_AUTH_MODEset to "zitadel" -
UDASH_AUTH_ZITADEL_FILEKEY: Path to the Zitadel service account key file, requires
UDASH_AUTH_MODEset to "zitadel" -
UDASH_DB_URI: Define the postgresql URI
Even though the Udash frontend is a client-side javascript application, it is configured entirely
at runtime through a single config.json, served next to the application at
/usr/share/nginx/html/config.json. The page fetches it before loading the bundle, so the same
image serves an open deployment and an authenticated one without a rebuild.
{
"AUTH_ENABLED": false,
"OAUTH_DOMAIN": "https://your-instance.zitadel.cloud",
"OAUTH_CLIENTID": "86FVLxxxxxxxxxxxxxxxxxx",
"OAUTH_SCOPE": "openid profile email offline_access urn:zitadel:iam:org:project:id:PROJECT_ID:aud",
"OAUTH_AUDIENCE": "https://app.updatecli.io/api",
"API_BASE_URL": "/api",
"APP_BASE_PATH": "/",
"MAX_HISTORY_DAYS": 30
}-
AUTH_ENABLED: Require authentication. Defaults to
false. -
OAUTH_DOMAIN: The provider issuer URL.
-
OAUTH_CLIENTID: The client ID of the SPA application.
-
OAUTH_SCOPE: Requested scopes. Defaults to
openid profile email offline_access, whereoffline_accessis what enables silent token renewal. Zitadel additionally requires the project audience scopeurn:zitadel:iam:org:project:id:<PROJECT_ID>:aud. -
OAUTH_AUDIENCE: Not used by the frontend itself. It is read by Updatecli, see below.
-
API_BASE_URL: Where the browser reaches the API. Relative (
/api) for same-host routing, or an absolute URL when the API lives on its own domain. Defaults to/api. -
APP_BASE_PATH: Base path of the SPA, for mounting it below a subpath such as
/udash/. Defaults to/. -
MAX_HISTORY_DAYS: How far back the date filter and the activity chart may reach. Defaults to
30and is capped at the API’s own maximum of366.
config.json is also what Updatecli reads to discover the oauth settings when running
updatecli udash login. It fetches <url>/config.json and takes OAUTH_DOMAIN, OAUTH_CLIENTID,
and OAUTH_AUDIENCE from it, so an authenticated deployment has to publish OAUTH_AUDIENCE there
even though the frontend never reads it. The value doubles as the API URL Updatecli stores, so it
should be the API base URL the CLI is expected to publish to.
Updatecli is expected to run as usual from CI environment.
But it must know where to publish before uploading any reports, by running:
updatecli udash login "https://app.updatecli.io" --experimental
Then any apply/diff command will upload pipeline reports, as long as it is also run with
--experimental. Without that flag the upload is skipped silently.
Against a deployment with authentication enabled, pass at least one oauth flag so the command runs the PKCE flow rather than just recording the endpoint:
updatecli udash login --oauth-clientId "<client id>" "https://app.updatecli.io" --experimental
The remaining oauth settings are then discovered from <url>/config.json.
--api-url sets the API endpoint, defaulting to <url>/api. Note that the PKCE flow stores the
oauth audience as the API URL instead, so on an authenticated deployment the audience and the API
base URL have to be the same value.