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.
Updating the Agent
Keep the agent current to pick up security patches and new capabilities:
# Update agent to the latest version
astroctl infra k8s register agent update --cluster-name my-cluster
# Preview the updated manifest before applying
astroctl infra k8s register agent update --cluster-name my-cluster --dry-run
The update re-generates the agent manifest with the latest image and refreshed certificates, then applies it to your cluster. The cluster must be in REGISTERED state to update.
Security
What you get out of the box
| What | How |
|---|---|
| No inbound ports required | The agent initiates an outbound connection to the platform — your cluster's API server does not need to be publicly reachable. No firewall rules, VPN, or network peering needed. |
| mTLS authentication | Unique certificates are generated per registration. Both sides verify identity on every connection. Certificates are rotated on agent update. |
| No stored K8s credentials | The platform never holds a kubeconfig, service account token, or direct API access to your cluster. All communication goes through the encrypted agent tunnel. |
| Namespace isolation | The agent runs in its own namespace (astroplatform-system) and does not modify your existing workloads or cluster configuration. |
| Org ownership guard | Attempting to register a cluster that already has an agent from a different organization is blocked — the existing registration must be removed first. |
How to harden further
Restrict agent egress to the platform only
The agent only needs outbound HTTPS (443) to the platform tunnel endpoint. Apply a Kubernetes NetworkPolicy to the astroplatform-system namespace to block all other egress from the agent pods.
Review the manifest before deploying
Use --dry-run to inspect exactly what will be applied before it touches your cluster:
astroctl infra k8s register --cluster-name my-cluster --dry-run
Or download the manifest separately for team review before installing:
astroctl infra k8s register --cluster-name my-cluster --no-install
astroctl infra k8s register manifest --cluster-name my-cluster
Keep the agent updated
Run astroctl infra k8s register agent update periodically to pick up security patches and rotate certificates.
Registered clusters have a stronger network security posture than managed EKS, GKE, or AKS clusters. Since the agent creates an outbound tunnel, your cluster's API server never needs to be exposed to the internet — even for platform operations like application deployments.
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