Connecting Clusters

Connect your Kubernetes clusters to Skyhook to enable monitoring, resource management, and automated deployments. Skyhook works with existing clusters; no need to provision new infrastructure.

New to Skyhook? Consider using the Onboarding Guide for guided setup. It walks you through cluster connection, ArgoCD installation, and addon configuration automatically.

This guide covers manual cluster connection for users who prefer direct control or already have infrastructure in place.

Supported Cloud Providers

Google Cloud (GKE)

Fully supported

AWS (EKS)

Fully supported

Azure (AKS)

Private Beta

☸

Any Kubernetes

Fully supported

Interested in Azure support? Contact us to join the private beta.

Prerequisites

Before connecting a cluster, ensure you have:

Required

Existing Kubernetes cluster (GKE, EKS, AKS, or any conformant Kubernetes distribution)
kubectl and helm installed locally
Cluster access with permissions to install workloads
Cloud provider CLI configured and authenticated (gcloud, aws, or az CLI) - only needed for managed cloud clusters

Highly Recommended: Cluster Addons

Skyhook works best with these common Kubernetes addons:

nginx-ingress controller - Automated ingress configuration and TLS management
cert-manager - Automated certificate issuance and renewal

Without nginx-ingress and cert-manager, Skyhook can still monitor your cluster, but you’ll need to manually handle ingress configuration and certificate management for your services.

Addon Management: ArgoCD vs Manual Installation

We strongly recommend managing addons with ArgoCD for GitOps-based automation:

ArgoCD (Recommended)
Manual Helm Installation

Why ArgoCD?

Version-controlled addon configurations in Git
Automated deployment and updates across clusters
Drift detection and self-healing
Centralized management from Skyhook UI

Setup Steps:

Install ArgoCD on your management cluster (guide)
Configure your GitOps repository
Use Skyhook’s GitOps settings page to add addons
ArgoCD automatically deploys and maintains addons across your clusters

See the GitOps with ArgoCD documentation for detailed instructions.

The Onboarding Guide automates ArgoCD setup and addon configuration for you.

If you prefer not to use ArgoCD, you can install addons manually with helm:nginx-ingress:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace

cert-manager:

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set installCRDs=true

With manual installation, you’ll need to handle addon updates, configuration changes, and multi-cluster consistency yourself.

Configuring cert-manager ClusterIssuer

Via ArgoCD/Skyhook Addon
Manual Installation

No manual configuration needed! When you install cert-manager through Skyhook’s addon system (via ArgoCD), a ClusterIssuer is automatically created and configured with Let’s Encrypt.

The addon takes care of:

Creating the letsencrypt ClusterIssuer
Configuring HTTP01 challenge solver
Setting up the necessary secrets

You can view and modify the ClusterIssuer configuration through the Addons page.

If you installed cert-manager manually with helm, you’ll need to create a ClusterIssuer yourself:

kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt
  namespace: cert-manager
spec:
  acme:
    # Replace with your email address
    email: user@example.com
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

Replace user@example.com with your actual email address. Let’s Encrypt uses this to notify you about certificate expiration and account issues.

Connecting a Cluster

Using the CLI (recommended)

If you already have a kubectl context for the cluster, the fastest path is:

skyhook onboard cluster connect

skyhook onboard cluster connect detects your cluster from the current kubectl context, auto-fills the cloud provider / account / region, registers the cluster with Skyhook, and runs the helm install for the connector — all in one shot. You can pass --context <ctx> to target a specific context, --all to register every unconnected context at once, or --dry-run to preview. Once the connector comes online, skip to Step 5: Verify Connection below. For users who prefer the UI, or clusters where the CLI’s auto-detection doesn’t fit your environment, the per-provider flows below walk through it manually.

Google Cloud (GKE)
AWS (EKS)
Azure (AKS) - Private Beta
Any Kubernetes (BYOK)

Step 1: Gather Cluster Information

You’ll need:

Cluster name (exact name from GCP Console)
GCP Project ID (e.g., koala-ops-123)
Zone (e.g., us-west1-a) or Region (e.g., us-west1 for regional clusters)

Find these values in the GCP Console.

Step 2: Authenticate to Your Cluster

Make sure gcloud and the GKE auth plugin are installed:

gcloud components install gke-gcloud-auth-plugin

Authenticate to Google Cloud:

gcloud auth login

Get cluster credentials:

gcloud container clusters get-credentials CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --project=PROJECT_ID

Verify access:

kubectl cluster-info

Step 3: Register the Cluster

Navigate to Clusters → Connect in the Skyhook UI
Select GCP as the cloud provider
Fill in your cluster details:
- Cluster name
- GCP Project ID
- Zone or Region
Click Register Cluster

After registration, you’ll see a helm install command with your cluster’s unique API key.

Step 4: Install the Cluster Connector

Copy the helm install command from the previous step and run it in your terminal:

helm repo add skyhook https://skyhook-io.github.io/helm-charts
helm repo update
helm upgrade --install skyhook-cluster-connector skyhook/skyhook-cluster-connector \
--namespace skyhook-cluster-connector --create-namespace \
--set apiKey=<YOUR_CLUSTER_API_KEY>

The Cluster Connector will start syncing data to Skyhook in under a minute.

Step 5: Verify Connection

Return to Clusters → List in the Skyhook UI. Your cluster status should change from WAITING FOR CHECK-IN (blue) to ONLINE (green) in under a minute.The Cluster Connector fetches cluster data on-demand when you use the Skyhook UI, ensuring you always see current information without unnecessary polling.

Step 1: Gather Cluster Information

You’ll need:

Cluster name (exact name from AWS Console)
AWS Account ID (12-digit account number)
Region (e.g., us-east-1)

Find these values in the EKS Console.

Step 2: Authenticate to Your Cluster

Configure the AWS CLI if you haven’t already:

aws configure
# or for SSO:
aws configure sso

List your configured profiles:

aws configure list-profiles

Update your kubeconfig for the EKS cluster:

aws eks update-kubeconfig \
  --name CLUSTER_NAME \
  --region REGION \
  --profile YOUR_PROFILE_NAME

Verify access:

kubectl cluster-info

Step 3: Register the Cluster

Navigate to Clusters → Connect in the Skyhook UI
Select AWS as the cloud provider
Fill in your cluster details:
- Cluster name
- AWS Account ID
- Region
Click Register Cluster

After registration, you’ll see a helm install command with your cluster’s unique API key.

Step 4: Install the Cluster Connector

Copy the helm install command from the previous step and run it in your terminal:

helm install skyhook-cluster-connector oci://us-docker.pkg.dev/skyhook-artifacts/skyhook-public/skyhook-cluster-connector \
  --set apiKey=YOUR_CLUSTER_API_KEY \
  --namespace skyhook-cluster-connector \
  --create-namespace

The Cluster Connector will start syncing data to Skyhook within a few minutes.

Step 5: Verify Connection

Return to Clusters → List in the Skyhook UI. Your cluster status should change from WAITING FOR CHECK-IN to ONLINE within 2-3 minutes.

Skyhook supports any conformant Kubernetes cluster - on-prem, bare-metal, OVH, DigitalOcean, Linode, Civo, k3s, or any other distribution.

We strongly recommend installing ArgoCD on BYOK clusters. While Skyhook’s CI/CD pipelines work without it, ArgoCD unlocks the full platform experience: automated addon management (cert-manager, nginx-ingress, OpenCost), GitOps-based configuration, drift detection, and multi-cluster consistency. The onboarding wizard will guide you through ArgoCD installation after connecting your cluster.

Step 1: Verify Cluster Access

Ensure your kubeconfig is configured and you can access the cluster:

kubectl cluster-info
kubectl get nodes

No cloud provider CLI is required.

Step 2: Register the Cluster

Navigate to Clusters → Connect in the Skyhook UI
Select Other / On-Prem as the cloud provider
Fill in your cluster details:
- Cluster name (required) - a unique name for this cluster within your organization
- Location (optional) - where the cluster runs (e.g., us-east, dc-1, paris)
- Organization / Group (optional) - a label to group clusters (e.g., team name, datacenter, account)
Click Register Cluster

After registration, you’ll see a helm install command with your cluster’s unique API key.

Step 3: Install the Cluster Connector

Copy the helm install command from the previous step and run it:

helm repo add skyhook https://skyhook-io.github.io/helm-charts
helm repo update
helm upgrade --install skyhook-connector skyhook/skyhook-connector \
  --namespace skyhook-connector --create-namespace \
  --set apiKey=<YOUR_CLUSTER_API_KEY>

The connector runs as a pod in your cluster and communicates outbound to the Skyhook API. No inbound ports or public endpoints are required.

Step 4: Verify Connection

Return to Clusters → List in the Skyhook UI. Your cluster status should change from WAITING FOR CHECK-IN to ONLINE within a minute.

What Works Differently with BYOK

Most Skyhook features work identically on BYOK clusters. A few things to be aware of:

Logging links: Skyhook won’t generate cloud-specific log console links (e.g., CloudWatch, Cloud Logging). Configure a custom logging URL template in your organization settings if you use Grafana, ELK, or another logging platform.
Cloud console links: Links to cloud provider consoles (GCP Console, AWS Console) won’t appear for BYOK clusters.
Cost tracking: FinOps cloud cost integration requires a cloud billing account. OpenCost still provides cluster-level resource metrics without cloud billing data.
Container registry: Use any OCI-compliant registry (Docker Hub, GitHub Container Registry, Harbor, Quay, etc.). Configure imagePullSecrets in your cluster if your registry requires authentication.
Secrets management: External Secrets Operator works with any backend (HashiCorp Vault, AWS Secrets Manager, etc.). For BYOK, Vault or Sealed Secrets are common choices.
Storage classes: Addons that need persistent storage (e.g., Prometheus via OpenCost) default to the standard StorageClass. If your cluster uses a different default, update the storage class in the addon configuration.
Ingress: nginx-ingress works on any cluster. Cloud-specific ingress controllers (AWS ALB, GCE) are not applicable.

Configuring DNS for Services

To expose services via ingress with custom domains, configure your DNS provider to point to your cluster’s load balancer IP address.

Single Cluster Setup

Find your cluster’s external load balancer IP in the Cluster detail page (Networking section) or in your cloud provider’s console. Create an A record in your DNS provider:

example.com  →  A  →  <CLUSTER_LOAD_BALANCER_IP>
*.example.com  →  A  →  <CLUSTER_LOAD_BALANCER_IP>

Multi-Cluster Load Balancing

If you’re using a global load balancer across multiple clusters, continue managing DNS through your existing setup. Skyhook doesn’t currently automate multi-cluster load balancing.

Troubleshooting

Cluster Status Stuck on “WAITING FOR CHECK-IN”

If your cluster remains in WAITING FOR CHECK-IN status for more than 5 minutes:

Verify the Cluster Connector pod is running:
```
kubectl get pods -n skyhook-connector
```
Expected output: STATUS: Running

Check connector logs for errors:

kubectl logs -n skyhook-connector -l app.kubernetes.io/name=skyhook-connector --tail=50

Common issues:
- Firewall blocking egress: Ensure your cluster can reach *.skyhook.io on port 443
- Wrong API key: Verify you used the helm command from the Skyhook UI (includes correct API key)
- RBAC permissions: The agent needs cluster-wide read permissions (automatically configured by the helm chart)

Permission Errors During Helm Install

Make sure you have admin permissions in the cluster:

kubectl auth can-i create clusterrole

If you see “no”, contact your cluster administrator for the necessary permissions.

Next Steps

View Cluster Health

Monitor cluster status and detect problems

Inspect Resources

Drill down into pods, services, and more

Manage Services

Deploy and configure applications

Introduction

Getting Started

Application Features

Infrastructure & Platform

Observability

Settings

AI Assistant

Terms and Privacy Policy

​Supported Cloud Providers

​Prerequisites

​Required

​Highly Recommended: Cluster Addons

​Addon Management: ArgoCD vs Manual Installation

​Configuring cert-manager ClusterIssuer

​Connecting a Cluster

​Using the CLI (recommended)

​Step 1: Gather Cluster Information

​Step 2: Authenticate to Your Cluster

​Step 3: Register the Cluster

​Step 4: Install the Cluster Connector

​Step 5: Verify Connection

​Step 1: Gather Cluster Information

​Step 2: Authenticate to Your Cluster

​Step 3: Register the Cluster

​Step 4: Install the Cluster Connector

​Step 5: Verify Connection

​Step 1: Verify Cluster Access

​Step 2: Register the Cluster

​Step 3: Install the Cluster Connector

​Step 4: Verify Connection

​What Works Differently with BYOK

​Configuring DNS for Services

​Single Cluster Setup

​Multi-Cluster Load Balancing

​Troubleshooting

​Cluster Status Stuck on “WAITING FOR CHECK-IN”

​Permission Errors During Helm Install

​Next Steps

View Cluster Health

Inspect Resources

Manage Services

Supported Cloud Providers

Prerequisites

Required

Highly Recommended: Cluster Addons

Addon Management: ArgoCD vs Manual Installation

Configuring cert-manager ClusterIssuer

Connecting a Cluster

Using the CLI (recommended)

Step 1: Gather Cluster Information

Step 2: Authenticate to Your Cluster

Step 3: Register the Cluster

Step 4: Install the Cluster Connector

Step 5: Verify Connection

Step 1: Gather Cluster Information

Step 2: Authenticate to Your Cluster

Step 3: Register the Cluster

Step 4: Install the Cluster Connector

Step 5: Verify Connection

Step 1: Verify Cluster Access

Step 2: Register the Cluster

Step 3: Install the Cluster Connector

Step 4: Verify Connection

What Works Differently with BYOK

Configuring DNS for Services

Single Cluster Setup

Multi-Cluster Load Balancing

Troubleshooting

Cluster Status Stuck on “WAITING FOR CHECK-IN”

Permission Errors During Helm Install

Next Steps