Kuma OAuth2 Proxy Application Template

Below is a cleaned, structured, and user-guide–friendly rewrite of the entire document. The content is reorganized, wording is simplified, headings are consistent, and steps are easier to follow—without changing technical meaning.

Kuma OAuth2 Proxy application template

The Kuma OAuth2 Proxy Application Template deploys a Kuma Control Plane pre-integrated with oauth2-proxy, enabling centralized OIDC authentication through Kosmos SSO. This allows secure access to the Kuma GUI based on Kosmos user and team roles.

Authentication flow

User → Kosmos SSO → OAuth2 Proxy → Kuma Control Plane (GUI)

This template is deployed to a target Kubernetes cluster using a Kosmos Task.

For additional details, refer to:

Parameters

Name	Type	Required	Created by Kosmos controller	Description	Example / default
kuma_control _plane_mode	string	✅	❌	Kuma control plane deployment mode (`global` or `zone`).	`zone`
kuma_control _plane_log_level	string	✅	❌	Logging level for Kuma control plane.	`info`
kuma_control _plane_enable _auto_scaling	string (bool)	✅	❌	Enable auto-scaling for the control plane.	`'false'`
kuma_ingress _enable	string (bool)	✅	❌	Enable centralized ingress for multi-zone setup.	`'false'`
kuma_egress _enable	string (bool)	✅	❌	Enable centralized egress for multi-zone setup.	`'false'`
kuma_control _plane_values	string	❌	❌	Additional Helm values for the Kuma control plane.	See example kuma_control_plane_values .
kuma_helm _values	string	❌	❌	Additional global Helm values for Kuma.	See example kuma_helm_values
oauth2proxy_http _scheme	string	✅	❌	HTTP scheme used by OAuth2 Proxy.	`http`
oauth2proxy _upstream	string	✅	❌	Upstream service URL after successful authentication.	`http://kuma-control-plane.<SVC_NAMESPACE>.svc.cluster.local:5681`
oauth2proxy _cookie_secret	string	✅	❌	Secret for encrypting OAuth2 Proxy cookies.	Generated via `openssl rand -base64 32`
oauth2proxy_ingress _enabled	string (bool)	✅	❌	Enable ingress for OAuth2 Proxy.	`'false'`
oauth2proxy_ingress _values	string	❌	❌	Helm values for OAuth2 Proxy ingress.	See example oauth2proxy_ingress_values
oauth2proxy_helm _values	string	✅	❌	Additional Helm values for OAuth2 Proxy.	`service.type: ClusterIP`
app_secret	string	✅	✅	OAuth2 Proxy secret name created by Kosmos.	`oauth-proxy-secret`
app_redirect_url	string	✅	✅	Redirect URL after successful login.	`http://localhost:8080/oauth2/callback`
approle_users _viewer	comma-separated string	❌	✅	Users allowed to access the Kuma GUI.	`user1,user2`
approle_teams _viewer	comma-separated string	❌	✅	Teams allowed to access the Kuma GUI.	`team1,team2`

Example: `kuma_control_plane_values`

|-
  resources:
    requests:
      cpu: 500m
      memory: 256Mi
    limits:
      memory: 256Mi

Example: `kuma_helm_values`

|-
  cni:
    enabled: false

Example: `oauth2proxy_ingress_values`

|-
  annotations:
    nginx.org/redirect-to-https: "true"
  className: nginx
  path: /
  pathType: Prefix
  hosts:
    - kuma-demo.notactualdomain.site
  tls:
    - secretName: oauth2-tls-cert
      hosts:
        - kuma-demo.notactualdomain.site

Installation setup

Prerequisites

Fleet cluster or Devspace vCluster access
Kosmos CLI: Version v4.3.15 or later Refer to the latest available version
Target namespace already exists in the vCluster
kubectl installed

Installation via Kosmos CLI

Step 1: Log in to Kosmos CLI

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 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 app template

Ensure the app template exists:

kosmos get app --name kuma-oauth2proxy-auth

Example output:

┌────────────────────────┬─────────────────────────────┬─────────────────────────────────────────────────┬───────┐
│ NAME                   │ DISPLAY NAME                │ DESCRIPTION                                     │ OWNER │
├────────────────────────┼─────────────────────────────┼─────────────────────────────────────────────────┼───────┤
│ kuma-oauth2proxy-auth  │ Kuma With Oauth2-Proxy      │ Kuma Installation with OAuth2 Proxy integration │ admin │
│                        │ integration for Kosmos-SSO  │                                                 │       │
└────────────────────────┴─────────────────────────────┴─────────────────────────────────────────────────┴───────┘

Step 3: Create the parameters file

Create a file named kuma-parameters.yaml:

kuma_control_plane_mode: zone
kuma_control_plane_log_level: info
kuma_control_plane_enable_auto_scaling: 'false'
kuma_ingress_enable: 'false'
kuma_egress_enable: 'false'

kuma_control_plane_values: "" # for this test we will skip this control plane section
kuma_ingress_values: ""
kuma_egress_values: ""
kuma_helm_values: ""

oauth2proxy_http_scheme: http
oauth2proxy_upstream: http://kuma-control-plane.<kuma-system-namespace>.svc.cluster.local:5681
oauth2proxy_cookie_secret: <generated-secret>
oauth2proxy_ingress_enabled: 'false'

app_redirect_url: http://localhost:8080/oauth2/callback
app_secret: oauth-proxy-secret
approle_users_viewer: user1,user2 # add your username if you want to add yourself as viewer
approle_teams_viewer: ""  # if you want to assign devspaceteam, you can add it on here

Step 4: Install the app

Install using kosmos install app command. For this test, we will use devspace sample-devspace and vcluster sample-vcluster:

kosmos install app --name kuma-oauth2proxy-auth --parameter-file kuma-parameters.yaml \
  --release-name kuma-oauth2proxy-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

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 kuma-oauth2proxy-auth from the list.

Step 5: Configure parameters

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

Assign your username to the Viewer role in the Application Roles section.

Step 6: Install the app

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

Installed resources

This template deploys:

Kuma Control Plane – core service mesh component
OAuth2 Proxy – handles authentication via Kosmos SSO

Deployment

Pods

Service

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 OAuth2 Proxy

After switching to the correct Kubernetes context, port-forward the OAuth2 Proxy service to your local machine. This enables local environment for authorization testing.

kubectl port-forward -n sample svc/kuma-oauth2proxy-auth-oauth2-proxy 8080:80

Note: The local port 8080 must match the port specified in the app_redirect_url parameter (http://localhost:8080). Port 4180 is the default service port for OAuth2 Proxy.

Authorization Test

Open the following URL in your local browser:

http://localhost:8080/gui

You will be redirected to Kosmos SSO. On first login, click Grant to continue.

Users assigned to the viewer role can access the Kuma GUI. Others are denied.

Verify authorization

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

After a successful login:

Sidecar injection verification

Prerequisites

kubectl installed and configured

Install an example microservice

For this verification, you will deploy a simple test pod defined in demo-pod.yaml.

Create the following file:

apiVersion: v1
kind: Pod
metadata:
  name: demo-pod
  namespace: demo
spec:
  containers:
    - name: alpine
      image: alpine:latest
      command: ["/bin/sh", "-c", "apk add --no-cache bash curl && sleep 3600"]

Enable sidecar injection

Kuma injects sidecars at the namespace level. First, create a namespace and enable sidecar injection by adding the required label.

kubectl create namespace demo

kubectl label namespace demo kuma.io/sidecar-injection=enabled

Verify that the label is applied:

kubectl get namespace demo --show-labels

Example output:

NAME   STATUS   AGE     LABELS
demo   Active   6h57m   kubernetes.io/metadata.name=demo,kuma.io/sidecar-injection=enabled

Deploy the test pod

Apply the pod manifest to the demo namespace:

kubectl apply -f demo-pod.yaml

Verify sidecar injection

Check the pod status:

kubectl get pod -n demo

Example output:

NAME       READY   STATUS    RESTARTS   AGE
demo-pod   2/2     Running   0          70s

A READY status of 2/2 confirms that:

One container is the application container
One container is the Kuma sidecar

This verifies that sidecar injection is working correctly.

Edit this page on GitHub

Kuma OAuth2 Proxy Application Template