Cosmog setup: Kubernetes setup

This guide helps you set up Cosmog for applications running on **Kubernetes. **Make sure you’ve completed the prerequisites before continuing.

Specific network requirements for Kubernetes

The Cosmog client uses hostNetwork: true.

This means that the Cosmog pod uses the host machine’s network directly. This allows it to communicate with internal cluster services and establish the secure tunnel.

This is specific for Kubernetes, so if your applications are not inside Kubernetes, use the Standard platform setup.

Creating a Cosmog profile

You’ll have to configure a Cosmog profile to get started.

Method 1: From the tunneling section

• Click on **Tunneling, **located in the application dashboard.

• This will open up the Cosmog configuration side panel.

• Click on Create new profile.

• Select **Kubernetes. **(Kubernetes integration steps are explained after this section)

• Select the Cosmog profile from the dropdown and click Save.

Method 2: While creating an application

.

• Create a new application.

• Enter the application details.

• Enable: ‘This URL is only accessible within my local network and is not available publicly.’

• Select an existing Cosmog profile or click Add new.

• Choose **Kubernetes. **(Kubernetes integration steps are explained after this section)

• Click Save to complete setup.

Profile configuration

While creating the profile, you’ll need to provide:

Namespace

The Kubernetes namespace where the Cosmog client will be deployed.

Example: dev, staging, prod.

Cluster domain

The internal DNS domain of your Kubernetes cluster, usually ending with .svc.cluster.local. 

Bridge IP

The Bridge IP is used to route traffic from Beagle Security’s test engine to your Kubernetes cluster through the secure tunnel. It must not conflict with the test range IPs. Choose a suitable bridge IP from the provided IP ranges.

Test IP Range

The IP range of the services or applications you want to test.

Format: CIDR (example: 192.168.1.0/24).

Kubernetes integration for Cosmog

Follow these steps to install and connect the Cosmog client inside your Kubernetes cluster:

• Select Kubernetes.

• Provide the necessary information.

• Click **Save. **Your profile is now created.

• Open your newly created Cosmog profile and click on Install.

• Copy the command shown in the pop up.

• Run the command in your Kubernetes environment using one of the following methods:
• • Helm charts.

• Applying manifest with kubectl apply.

-> It is a binary script that runs the Cosmog client as a Docker container

-> It will install Docker automatically if it is not already installed

-> It does not require Docker Compose or any manual setup

-> It starts the Cosmog client and establishes the secure tunnel

• The Cosmog client will be set up in the default namespace, unless specified otherwise. 

• Once the setup is complete, you can start the test from the Beagle Security dashboard.

• When the test starts
• • The cosmog server is initialized automatically.
  • The cosmog client connects to the server.

Once the connection is verified, Beagle Security starts the security test. All traffic flows securely through the tunnel. 

Scan limits

The number of scans you can run at the same time depends on your plan. For example, some plans allow up to 5 concurrent scans.

Each scan sends traffic through your network. Running multiple scans can increase bandwidth usage and this may affect performance depending on your network capacity.

So the recommendation is to plan scans based on your available network resources and avoid running multiple scans at the same time.

Troubleshooting

If the tunnel fails to connect:

• Check UDP: Verify that your firewall allows UDP.

• Check DNS: Ensure the container can resolve external domains.

Error handling

Certain errors may occur when you initiate a test if your Cosmog profile or client is not set up correctly. Understanding the following conditions can help you fix the issues when starting a test. 

You can check the status of your setup on your Beagle Security dashboard.

Go to:

Dashboard → Application → select that current internal app → testing → tunneling

Case 1: Everything is down

• Cosmog Server status: Down
• Cosmog Client status: Down
• Application status: Down

Possible reasons

• The security test was not started.
• Cosmog profile was not created.
• Profile was deleted.

What to do

• Start the test
• Create or recreate the Cosmog profile

Case 2: Client Not Running

• Cosmog Server status: Up
• Cosmog Client status: Down
• Application status: Down

Possible reasons

• Cosmog client is not installed.
• Cosmog client is not running properly. In such a case, please get in touch with our support team.

What to do

• Run the installation command again.
• Start the client using Cosmog Start.
• If the issue continues, contact support.

Case 3: Application Not Reachable

• Cosmog Server status: Up
• Cosmog Client status: Up
• Application status: Down

Possible reason

• Beagle Security cannot access your application.

What to do

• Check the configured IP range.
• Make sure the application is running.
• Verify it is accessible within your internal network.

Updated on: 06/05/2026