Kiali and Istio w/ Kosmos SSO Template

Overview #

The Kiali App Template provides a monitoring solution with built-in single sign-on (SSO) integration through Kosmos. This template automatically deploys Kiali with preconfigured OIDC authentication, allowing users to sign in using their Kosmos account and removing the need to manage separate credentials.

About the template #

This template is designed to be deployed to a target Kubernetes cluster using a Kosmos Task. It uses a custom Helm chart to install and configure the following components:

• Istio Base
• Istio Control Plane (istiod)
• Kiali Server running in sidecar mode

To simplify access and authentication, the template integrates Kosmos OIDC SSO, enabling seamless login to Kiali directly through Kosmos.

For more detailed information, refer to the official documentation:

• Kiali documentation
• Istio service mesh documentation

About Istio and Kiali #

• Istio is an open-source service mesh that provides a transparent network layer for microservices. It helps manage traffic, enforce security, and observe service behavior.
• Kiali is a management and observability console for the Istio service mesh, offering visibility into service topology, health, and traffic flows.

About the authentication flow #

Kiali uses Kosmos for single sign-on (SSO). The authentication flow works as follows:

User → Kosmos SSO → Kiali console

When a user accesses the Kiali UI, they are redirected to Kosmos for authentication. After a successful login, the user is automatically returned to the Kiali console with the appropriate access permissions.

Parameters #

Example: kiali_deployment_values #

service_type: ClusterIP
ingress:
  enabled: true
  override_yaml:
    spec:
      ingressClassName: nginx
      tls:
        - hosts:
            - kiali.notactualdomain.online
          secretName: kiali-tls-secret
      rules:
        - host: kiali.notactualdomain.online
          http:
            paths:
              - path: /
                pathType: Prefix
                backend:
                  service:
                    name: kiali
                    port:
                      number: 20001

Example: istio_base_deployment_values #

global:
  istioNamespace: istio-system

Example: istiod_deployment_values #

pilot:
  resources:
    requests:
      cpu: 500m
      memory: 512Mi

Prerequisites #

Before installing the Kiali App Template, ensure the following requirements are met:

• Access level: Fleet cluster or Devspace vCluster access
• Kosmos CLI: Version v4.3.15 or later Refer to the latest available version
• Namespace: The target namespace istio-system must already exist in the cluster

Installation via Kosmos CLI #

Step 1: Log in to the Kosmos CLI #

Log in to the Kosmos staging environment:

kosmos login https://console.kosmos.spcplatform.com/ --access-key $ACCESS_KEY

Example output:

09:02:17 done Successfully logged into Kosmos instance https://console.kosmos.spcplatform.com

Verify the currently logged-in user:

kosmos get currentuser

Example output:

┌─────────────┬─────────────────────┬──────────────────┬────────────────┬───────────────────┐
│ USERNAME    │ KUBERNETES NAME      │ DISPLAY NAME     │ EMAIL          │ TEAMS             │
├─────────────┼─────────────────────┼──────────────────┼────────────────┼───────────────────┤
│ user        │ user                │ user@mail.com    │ user@mail.com  │ Kosmos User Team  │
└─────────────┴─────────────────────┴──────────────────┴────────────────┴───────────────────┘

Step 2: Verify the Kiali app template #

Ensure that the Kiali app template exists in Kosmos:

kosmos get app --name kiali-istio-auth

Example output:

┌───────────────────┬───────────────────────────┬─────────────────────────────────────────────────┬───────┐
│ NAME              │ DISPLAY NAME              │ DESCRIPTION                                     │ OWNER │
├───────────────────┼───────────────────────────┼─────────────────────────────────────────────────┼───────┤
│ kiali-istio-auth  │ Kosmos Kiali and          │ Automated Kosmos Kiali and Istio w/ Kosmos SSO  │ admin │
│                   │ Istio w/ Kosmos SSO       │                                                 │       │
└───────────────────┴───────────────────────────┴─────────────────────────────────────────────────┴───────┘

Step 3: Create the parameters file #

Create a YAML file named parameters_file.yaml and define the app parameters:

approle_users_viewer: user1          # Add your username to grant yourself viewer access
approle_teams_viewer: ""             # Optionally add a team name for viewer access
app_redirect_url: http://localhost:20001/kiali
app_secret_mapping: '{"oidc-secret": "clientSecret"}'
app_secret: kiali-secret

# Optional Helm override values
istio_base_deployment_values: ""     # Additional Helm values for Istio base
istiod_deployment_values: ""         # Additional Helm values for Istio control plane
kiali_deployment_values: ""          # Additional Helm values for Kiali
kiali_grafana_endpoint: ""          # endpoint to a grafana service. leaving it empty will disable grafana integration
kiali_prometheus_endpoint: ""       # endpoint to a prometheus service. if left empty kiali will use http://prometheus.istio-system:9090 as a default. this endpoint cannot be disabled
kiali_external_services_values: ""  # additional values to expand kiali external services integration other than grafana and prometheus. use with caution

Step 4: Install the app on the target cluster #

Install the app using the kosmos install app command. In this example, the app is installed on:

• Devspace: sample-devspace
• vCluster: sample-vcluster

kosmos install app
  --name kiali-istio-auth \               # app template id
  --parameter-file parameters_file.yaml \ # Name of parameters file we have prepared above
  --release-name kiali-istio-auth \       # Name of the App
  --target-cluster sample-vcluster \      # Target v/cluster
  --devspace sample-devspace \            # Name of the Fleet or DevSpace. Use --fleet <FLEET_NAME> instead for Fleet.
  --target-namespace sample               # Namespace where the App is deployed

Example output:

09:32:40 done Successfully installed App 'sample-devspace'

Installation via Kosmos management console #

Step 1: Log in to the Kosmos UI #

Open the Kosmos management console and log in with your account:

https://console.kosmos.spcplatform.com/

Step 2: Navigate to your target vCluster #

Depending on where you want to install the app, navigate to one of the following:

• Devspace vCluster

  https://console.kosmos.spcplatform.com/devspaces/<Devspace Name>/vclusters/<VCluster Name>
  

• Fleet cluster

  https://console.kosmos.spcplatform.com/fleets/<Fleet Name>/clusters/<Cluster Name>
  

Step 3: Open the Apps section #

In the cluster view, select the Apps tab from the navigation menu.

Step 4: Start app installation #

Click the Install App button. A sidebar will appear—select Kosmos Kiali and Istio w/ Kosmos SSO from the list.

Step 5: Configure parameters #

Fill in the required parameters. You can refer to the parameters_file.yaml example from the CLI installation section.

In the Application Roles section at the bottom, add your username to the Viewer role to grant access to the Kiali UI.

Step 6: Install the app #

Click Install. A popup will appear showing the Helm installation logs.

After a short while, the app will be installed on the selected target cluster and will appear as shown below:

Resource validation #

This app template deploys the following components:

• Istio Base – installs the required Custom Resource Definitions (CRDs)
• Istio Control Plane (Service Mesh)
• Kiali with Kosmos SSO authentication

By default, all components are deployed into the istio-system namespace.

Once the installation is complete, verify that the pods and services are running correctly.

Verify pods #

kubectl get pods -n istio-system

Example output:

NAME                     READY   STATUS
istiod-7fc86f7fd-hgwwf   1/1     Running
kiali-b49d4bf97-ncg22    1/1     Running

Verify services #

kubectl get svc -n istio-system

Example output:

NAME     TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)
istiod   ClusterIP   10.100.250.33   <none>        15010/TCP,15012/TCP,443/TCP,15014/TCP
kiali    ClusterIP   10.100.24.193   <none>        20001/TCP,9090/TCP

Testing #

Prerequisites #

Before starting, ensure the following tool is installed:

• kubectl

Select the vCluster Kubernetes context #

Set your Kubernetes context based on where the app was installed.

Devspace vCluster #

kosmos use vcluster --name sample-vcluster --devspace sample-devspace

Fleet cluster #

kosmos use cluster sample-cluster --fleet sample-fleet

Authorization testing #

Port-forward the service #

After switching to the correct Kubernetes context, port-forward the Kiali service to your local machine. This enables local access to the Kiali UI for authorization testing.

kubectl port-forward -n istio-system svc/kiali 20001:20001

Note: The local port 20001 must match the value configured in the app_redirect_url parameter: http://localhost:20001/kiali

Test authorization flow #

Open the following URL in your local browser:

http://localhost:20001/kiali

You will be redirected to the Kosmos Auth login page. If this is your first login, a consent screen will appear. Click Grant to continue.

Verify authorization #

To confirm that authorization is working as expected, ensure your user ID is assigned the viewer role.

After a successful login:

• The Kiali dashboard is accessible.
• Your username appears in the upper-right corner of the Kiali UI.

Verify Istio integration #

To verify that Kiali is correctly integrated with Istio:

1. In the Kiali UI, navigate to the Mesh menu.
2. Confirm that the istiod control plane connection is visible.

Troubleshooting #

Common issues #

No task is created after clicking Install #

If no task appears after clicking the Install button:

• Ensure all required parameters are filled in.
• Double-check parameter values for typos or unintended spaces.
• Verify that the selected target cluster, namespace, and app template are correct.

SSO login fails #

If you are unable to log in through Kosmos SSO:

• Verify that app_redirect_url exactly matches the Kiali access URL.
• Confirm that your user ID or team is correctly assigned to the viewer role.
• Check role mappings in the Kosmos identity provider, especially Fleet or Devspace role permissions.
• Ensure the OIDC secret is correctly created and propagated to the target cluster.
• Confirm that the Kiali pod is running and has access to the required secret.

Edit this page on GitHub