Skip to main content

Breeze Installation on Private Kubernetes (TunHub)

Install Cloudaware Breeze Agent in a Kubernetes cluster that runs in a private network so Cloudaware can establish TunHub connectivity and collect Kubernetes data. The integration is for Linux only.

Use Case​

Use this setup when you need to:

  • Install Breeze Agent on an Amazon EKS, Azure Kubernetes Service (AKS), or Google Kubernetes Engine (GKE) private-network clusters.
  • Enable Cloudaware to access a private-network Kubernetes cluster through TunHub connectivity.
  • Support Kubernetes inventory collection.

How It Works​

The deployment creates a single-replica pod with two components:

  1. Init container - Runs once at pod startup (EKS only):

    • Fetches EC2 instance metadata and tags using IMDSv2
    • Retrieves node tags via AWS EC2 API (requires ec2:DescribeTags permission)
    • Stores tag data in a shared volume for the main container

  2. Main container - Runs the Breeze agent continuously:

    • Executes breeze-daemon which runs Breeze on schedule
    • Requires /dev/net/tun device for VPN tunnel creation
    • Runs with NET_ADMIN and NET_RAW capabilities for network operations
    • Runs as non-root user (UID 10000) for security
    • Performs readiness checks by verifying the tunnel interface (zcat) exists

The agent runs as a Kubernetes workload and establishes a VPN tunnel to Tunhub, enabling remote connectivity without direct network access to the cluster.

High-Level Setup Flow​

  1. Download the Breeze Agent installer from Cloudaware.
  2. Prepare the Breeze Agent files for containerization.
  3. Build and push the Breeze Agent Docker image.
  4. Prepare Kubernetes prerequisites.
  5. Configure the platform-specific deployment manifest.
  6. Deploy Breeze Agent to the Kubernetes cluster.
  7. Verify pod readiness and TunHub connectivity.

Installation Steps​

Download the Breeze Agent Installer​

  1. In Cloudaware, go to Admin.
  2. Find Breeze in DevOps Integrations. Click CONFIGURED.
  3. Download the Linux agent archive (the archive name uses the following format: breeze-agent.<breeze_key>.<breeze_version>.<build_arch>.linux.tgz).

Create a Docker Image​

  1. Unpack the Breeze Agent installer to the current directory:

    tar xvzf breeze-agent.<breeze_key>.0.x86_64.linux.tgz

    Where:

    • <breeze_key> is a placeholder for the customer-specific ID in the installer file name.
    • 0 is a Breeze version example.
    • x86_64 is a architecture build example.

    Replace breeze-agent.<breeze_key>.0.x86_64.linux.tgz with the name of the downloaded installer file.

  2. Remove TLS certificates from the unpacked directory to avoid baking secrets into the image:

    rm -f breeze-agent/etc/ssl/breeze-agent.crt
    rm -f breeze-agent/etc/ssl/breeze-agent.key
    note

    TLS certificates will be mounted from Kubernetes secrets at runtime.

    Alternative: Baking certificates into the image

    If you prefer to include TLS certificates in the image (not recommended for security):

    • Skip step 2 to keep certificates in the unpacked directory.
    • Build and push the image.
    • Comment out the TLS-related volumes and volumeMounts sections in breeze-agent-host-installer.yaml.

  3. Build Docker images:

    • For EKS (standard):

      docker build -t <registry_hostname>/breeze-agent:<tag> -f Dockerfile .

    • For AKS and GKE Autopilot builds, you must use Dockerfile.root:

      docker build -t <registry_hostname>/breeze-agent:<tag> -f Dockerfile.root .

    Where:

    • Replace <registry_hostname> and <tag> with your actual registry hostname and desired image tag, respectively.
    • The example <registry_hostname> format for EKS: <aws_account_id>.dkr.ecr.us-east-1.amazonaws.com.

  4. Push the image to your private registry:

    docker push <registry_hostname>/breeze-agent:<tag>

    Where:

    • Replace <registry_hostname> and <tag> with your actual registry hostname and desired image tag, respectively.
    • The example <registry_hostname> format for EKS: <aws_account_id>.dkr.ecr.us-east-1.amazonaws.com.

Run Deployment​

Before you begin:

  1. Deploy required RBAC resources:

    kubectl apply -f cloudaware-rbac.yaml

  2. Create a Kubernetes secret with your TLS certificates:

    kubectl create secret generic breeze-tls-secret \
      --from-file=tls.crt=path/to/breeze-agent.crt \
      --from-file=tls.key=path/to/breeze-agent.key

Amazon EKS​

  1. Ensure the node group IAM role has ec2:DescribeTags permission.

  2. Verify AWS metadata endpoints are accessible from pods. These paths are relative to the EC2 Instance Metadata Service (IMDS) base URL http://169.254.169.254/:

    • http://169.254.169.254/latest/api/token - IMDSv2 session token (PUT request)
    • http://169.254.169.254/latest/dynamic/instance-identity/document - instance identity document
    • http://169.254.169.254/latest/meta-data/services/partition - AWS partition (e.g., aws, aws-cn)
    • http://169.254.169.254/latest/meta-data/placement/region - AWS region of the instance

  3. Update the image reference in breeze-agent-eks.yaml.

  4. Apply the deployment:

    kubectl create -f breeze-agent-eks.yaml
    tip

    If metadata access is restricted, use breeze-agent-eks-wo-metadata.yaml, replacing <EKS_CLUSTER_ARN> with actual ARN.

Azure Kubernetes Service (AKS)​

note

AKS requires Dockerfile.root for image builds.

  1. Configure AKS-ACR integration (see Microsoft Azure documentation).

  2. Update the image reference in breeze-agent-aks.yaml

  3. Apply the deployment:

    kubectl create -f breeze-agent-aks.yaml

Google Kubernetes Engine (GKE)​

  1. Ensure cluster has permissions to pull from the registry (use Workload Identity or image pull secrets).

  2. Update the image reference in breeze-agent-gke.yaml.

  3. Apply the deployment:

    kubectl create -f breeze-agent-gke.yaml
    note

    GKE Autopilot: Use Dockerfile.root for builds and breeze-agent-gke-autopilot.yaml for deployment.

Verify Deployment​

The deployment includes a readiness probe that checks for the zcat tunnel interface. A pod reporting 1/1 Ready means the VPN tunnel is established and the agent is working. Note that the readiness probe starts 15 minutes after the container starts, so allow time for the pod to become ready.

  1. Check pod status:

    kubectl get pods -l app.kubernetes.io/name=breeze-agent

    Wait for the pod to show 1/1 under the READY column.

  2. Check init container logs (EKS only):

    kubectl logs <pod-name> -c breeze-agent-init

    Where:

    • Replace <pod-name> with your Kubernetes pod name.

    The output should show successful tag retrieval without errors.

  3. Check main container logs:

    kubectl logs <pod-name> -c breeze-agent

    Expected output includes "Checking prerequisites..." followed by "Starting Breeze daemon..." with no ERROR lines.

  4. Confirm the tunnel interface exists:

    kubectl exec <pod-name> -- grep zcat /proc/net/dev

    If the zcat interface is listed, the VPN tunnel is up and connectivity is established.