Kluctl Webui

• 1: Installation
• 2: Running locally
• 3: Azure AD Integration

1 - Installation

The Kluctl Webui can be installed by using a Git Include that refers to the webui deployment project. Example:

deployments:
  - git:
      url: https://github.com/kluctl/kluctl.git
      subDir: install/webui
      ref:
        tag: v2.25.1

Login

Static Users

By default, the Webui will automatically generate an static credentials for an admin and for a viewer user. These credentials can be extracted from the kluctl-system/webui-secret Secret after the Webui has started up for the first time. To get the admin password, invoke:

$ kubectl -n kluctl-system get secret webui-secret -o jsonpath='{.data.admin-password}' | base64 -d

For the viewer password, invoke:

$ kubectl -n kluctl-system get secret webui-secret -o jsonpath='{.data.viewer-password}' | base64 -d

If you do not want to rely on the Webui to generate those secrets, simply use your typical means of creating/updating the webui-secret Secret. The secret must contain values for admin-password, viewer-password.

OIDC Integration

The Webui offers an OIDC integration, which can be configured via CLI arguments.

For an example of an OIDC provider configurations, see Azure AD Integration.

Customization

Serving under a different path

By default, the webui is served under the /path. To change the path, pass the --prefix-path argument to the webui:

deployments:
  - git:
      url: https://github.com/kluctl/kluctl.git
      subDir: install/webui
      ref:
        tag: v2.25.1
    vars:
      - values:
          webui_args:
            - --path-prefix=/my-custom-prefix

Overriding the version

The image version of the Webui can be overriden with the kluctl_version arg:

deployments:
  - git:
      url: https://github.com/kluctl/kluctl.git
      subDir: install/webui
      ref:
        tag: main
    vars:
      - values:
          args:
            kluctl_version: v2.25.1

Passing arguments

You can pass arbitrary command line arguments to the webui by providing the webui_args arg:

deployments:
  - git:
      url: https://github.com/kluctl/kluctl.git
      subDir: install/webui
      ref:
        tag: v2.25.1
    vars:
      - values:
          webui_args:
            - --gops-agent

2 - Running locally

The Kluctl Webui can be run locally by simply invoking kluctl webui run. It will by default connect to your local Kubeconfig Context and expose the Webui on localhost. It will also open the browser for you.

Multiple Clusters

The Webui can already handle multiple clusters. Simply pass --context <context-name> multiple times to kluctl webui run. This will cause the Webui to listen for status updates on all passed clusters.

As noted in State of the Webui, the Webui is still in early stage and thus currently lacks sorting and filtering for clusters. This will be implemented in future releases.

3 - Azure AD Integration

Azure AD can be integrated via the OIDC integration.

Configure a new Azure AD App registration

Add a new Azure AD App registration

1. From the Azure Active Directory > App registrations menu, choose + New registration
2. Enter a Name for the application (e.g. Kluctl Webui).
3. Specify who can use the application (e.g. Accounts in this organizational directory only).
4. Enter Redirect URI (optional) as follows (replacing my-kluctl-webui-url with your Kluctl Webui URL), then choose Add.
   • Platform: Web
   • Redirect URI: https://<my-kluctl-webui-url>/auth/callback
5. When registration finishes, the Azure portal displays the app registration’s Overview pane. You see the Application (client) ID.

Add credentials a new Azure AD App registration

1. From the Certificates & secrets menu, choose + New client secret
2. Enter a Name for the secret (e.g. Kluctl Webui SSO).
   • Make sure to copy and save generated value. This is a value for the oidc-client-secret.

Setup permissions for Azure AD Application

1. From the API permissions menu, choose + Add a permission
2. Find User.Read permission (under Microsoft Graph) and grant it to the created application:
3. From the Token Configuration menu, choose + Add groups claim

Associate an Azure AD group to your Azure AD App registration

1. From the Azure Active Directory > Enterprise applications menu, search the App that you created (e.g. Kluctl Webui).
   • An Enterprise application with the same name of the Azure AD App registration is created when you add a new Azure AD App registration.
2. From the Users and groups menu of the app, add any users or groups requiring access to the service.

Configure the Kluctl Webui to use the new Azure AD App registration

Use the following configuration when installing the Webui. Replace occurrences of <directory_tenant_id>, <client_id>, <my-kluctl-webui-url> and <admin_group_id> with the appropriate values from above.

deployments:
  - path: secrets 
  - git:
      url: https://github.com/kluctl/kluctl.git
      subDir: install/webui
      ref:
         tag: v2.25.1
    vars:
      - values:
          args:
            webui_args:
              - --auth-oidc-issuer-url=https://login.microsoftonline.com/<directory_tenant_id>/v2.0
              - --auth-oidc-client-id=<client_id>
              - --auth-oidc-scope=openid
              - --auth-oidc-scope=profile
              - --auth-oidc-scope=email
              - --auth-oidc-redirect-url=https://<my-kluctl-webui-url>/auth/callback
              - --auth-oidc-group-claim=groups
              - --auth-oidc-admins-group=<admin_group_id>

Also, add webui-secrets.yaml inside the secrets subdirectory:

apiVersion: v1
kind: Secret
metadata:
  name: webui-secret
  namespace: kluctl-system
stringData:
  oidc-client-secret: "<client_secret>"

Please note that the client secret is sensitive data and should not be added unencrypted to you git repository. Consider encrypting it via SOPS.