Bring Your Own Kubernetes Cluster (BYOC)
Register any existing Kubernetes cluster with AstroPulse using a single command. Works with any cluster type -- EKS, GKE, AKS, on-premises, bare-metal, or even local development clusters like kind and minikube.
How It Works
When you register a cluster, the CLI deploys a lightweight agent into your cluster. The agent creates a secure outbound connection back to the AstroPulse platform. Once connected, your cluster appears in the platform and you can deploy applications, monitor workloads, and manage operations through the same unified interface as platform-provisioned clusters.
Key benefits:
- One command -- no manual firewall rules, VPN tunnels, or network configuration
- Outbound only -- the agent connects to the platform, no inbound ports required
- Universal -- works with any conformant Kubernetes cluster regardless of provider or location
- Non-invasive -- runs in its own namespace, does not modify your existing workloads
Prerequisites
Before registering a cluster, ensure you have:
| Requirement | Description |
|---|---|
| kubectl | kubectl configured with access to the target cluster |
| astroctl | astroctl downloaded and authenticated |
| Cluster access | kubectl context pointing to the cluster you want to register |
Quick Start
Register your current kubectl context with one command:
astroctl infra k8s register --cluster-name my-cluster
You can also add labels to organize your clusters:
astroctl infra k8s register --cluster-name my-cluster --labels env=prod --labels team=infra
The CLI will:
- Verify kubectl connectivity to your cluster
- Auto-detect the cluster region (when possible)
- Generate agent credentials and deployment manifest
- Deploy the agent to your cluster
- Report registration status
Registration Options
| Flag | Default | Description |
|---|---|---|
--cluster-name, -c | - | Name for the cluster in the platform (required unless using -f) |
--region | auto-detected | Cloud region override. Defaults to auto-detection from kubeconfig context |
--kubeconfig | current context | Path to kubeconfig file |
--context | current context | Kubernetes context to use |
--namespace | astroplatform-system | Namespace for agent deployment |
--no-install | false | Register only -- don't install the agent (for split-team workflows) |
--dry-run | false | Print agent manifest without deploying |
--labels | - | Labels for the cluster (key=value, can be repeated) |
--file, -f | - | YAML file with registration config. Use - for stdin |
Registration from YAML
You can define the registration in a YAML file:
clusterName: my-production-cluster
region: us-west-2
Apply it with:
astroctl infra k8s register -f registration.yaml
CLI flags like --dry-run, --no-install, --kubeconfig, and --context are preserved when using file input.
Split-Team Workflow
In enterprise environments, the platform team and infrastructure team may be separate. The --no-install flag supports this workflow:
Step 1: Platform team registers the cluster
astroctl infra k8s register --cluster-name prod-cluster --no-install
This creates the registration record without deploying anything to the target cluster.
Step 2: Infrastructure team installs the agent
# Install agent to the registered cluster
astroctl infra k8s register agent --cluster-name prod-cluster --context prod-k8s
# Or download the manifest for manual review first
astroctl infra k8s register manifest --cluster-name prod-cluster
Checking Registration Status
# Check registration status for a specific cluster
astroctl infra k8s register status --cluster-name my-cluster
# List all registered agents
astroctl infra k8s register agent list
# Stream real-time progress
astroctl infra k8s progress stream --cluster-name my-cluster
# Get cluster details
astroctl infra k8s get my-cluster
Connecting Cloud Provider Access
Registration is cloud-agnostic -- it works the same regardless of where your cluster runs. To enable cloud-specific operations (upgrades, scaling, cost analysis), connect your cloud provider credentials separately:
# Connect AWS credentials for an EKS cluster
astroctl cloud aws connect --cluster-name my-cluster --account-id 123456789012 --region us-west-2
# Connect GCP credentials for a GKE cluster
astroctl cloud gcp connect --cluster-name my-cluster --project-id my-project --region us-central1
# Connect Azure credentials for an AKS cluster
astroctl cloud azure connect --cluster-name my-cluster --subscription-id <uuid> --resource-group <resource-group> --region eastus
This separation means you can register a cluster immediately and connect cloud provider access later when needed.
Unregistering a Cluster
To remove a cluster from the platform:
astroctl infra k8s unregister --cluster-name my-cluster
This removes the agent deployment from your cluster and deletes the registration record from the platform. Your cluster and workloads are not affected.
Troubleshooting
Agent not connecting
If the agent is deployed but the cluster shows as disconnected:
# Check agent pod status
kubectl get pods -n astroplatform-system
# Check agent logs
kubectl logs -n astroplatform-system deploy/astro-agent
# Re-check registration status
astroctl infra k8s register status --cluster-name my-cluster
kubectl context issues
If registration fails with kubectl errors:
# Verify your current context
kubectl config current-context
kubectl cluster-info
# Specify a different context
astroctl infra k8s register --cluster-name my-cluster --context my-other-context
# Use a specific kubeconfig file
astroctl infra k8s register --cluster-name my-cluster --kubeconfig /path/to/kubeconfig
Resuming a failed registration
If registration was interrupted (network timeout, terminal closed):
astroctl infra k8s register resume --cluster-name my-cluster