Register a data plane cluster

After you install a data plane cluster, you must register it with the Astro Private Cloud control plane so that the Houston API can schedule Airflow Deployments.

Prerequisites

• The data plane Kubernetes cluster is up and reachable from the control plane network.
• Astronomer data plane components are installed and healthy on the data plane, including Commander.
• You know the base domain for the data plane ingress. For example, finance-dataplane-us-east-1.example.company.com.

Required fields

• Name: A unique identifier for the data plane cluster across the control plane. Names must be unique; pick a stable, human‑readable value. For example, finance-dataplane-us-east-1.
• Base domain: The base DNS domain served by the data plane ingress, in the format https://<domainPrefix>.<base_domain>. For example, finance-dataplane-us-east-1.example.company.com. This domain resolves to the data plane’s ingress endpoints.
• Cluster override: (Optional) Provide initial overrides to customize the cluster’s Deployment configuration. See Cluster override.

Register in the UI

Now you can proceed to create Airflow Deployments in this data plane.

Register through the Houston API

You can also register a data plane cluster by calling the registerCluster mutation on the Houston API. Send the request to https://houston.<your-base-domain>/v1 with a system service account or System Admin user token in the Authorization header. For details, see Authenticate to the Houston API.

1
mutation {
2
  registerCluster(
3
    name: "<cluster-name>"
4
    metadataUrl: "https://<commander-url>"
5
  ) {
6
    id
7
    name
8
    status
9
    healthStatus
10
  }
11
}

Argument reference:

When you call this mutation, Houston:

1. Validates that the name and metadataUrl are unique across registered clusters.
2. Calls GET /metadata on the supplied URL to fetch cluster details from Commander.
3. On success, creates the cluster row with status ACTIVE and stores Commander’s response under config and healthStatus.
4. On failure (network error, non-2xx response, TLS error), returns an error and persists no cluster row. Resolve the connectivity issue and retry.

After the mutation succeeds, monitor the cluster with the queries documented in Manage cluster status.

Related

• Clusters overview
• Deregister a cluster
• Update cluster configs with overrides
• Manage cluster status
• Authenticate to the Houston API