Cluster registration

A deployment space is a registered Kubernetes cluster ZopDay can deploy to. This page covers the BYOC path: registering a cluster you already have, so ZopDay can mint short-lived kubeconfigs and ship deploys to it. To have ZopDay create the cluster instead, see Provisioning clusters; that flow registers the cluster as a space automatically.

Before you start

• A connected cloud account with at least the cluster-registration permissions on Cloud permissions. On AWS, the account needs Provision Access, and any of the three connection methods works: WIF-Assume Role, IAM User (Static Keys) or Temporary Credentials.
• An existing cluster (EKS, GKE, or AKS) running on that account. If you don’t have one, provision one instead.
• The cluster’s identity in cloud terms: for AWS, cluster name + region; for GCP, cluster name + region + project; for Azure, cluster name + resource group + subscription.
• A Git repo with the application you want to ship, for the first deploy once the space is registered. See the Quickstart.

How it works

Registration has two steps:

1. Access grant (EKS only): ZopDay adds an EKS access entry for its identity on the cluster. ZopDay can now mint kubeconfigs for it.
2. Space promotion: the cluster is registered as a deployment space, so it shows up where you pick a space, such as when you create an environment.

These are two separate actions in the UI: the access grant is in Manage Clusters on the cloud account, and space promotion is on Infrastructure. They stay separate because the access grant is the security-sensitive operation. On promotion, ZopDay registers the space with discovery (so resources flow into reports) and with cost aggregation (so cost flows into showback), with no second connection.

Kubeauth: how ZopDay actually authenticates

ZopDay does not store a long-lived kubeconfig anywhere. Each deploy mints a fresh, short-lived kubeconfig at runtime from your cloud credentials. The deploy pod holds zero standing credentials on your cluster.

EKS and GKE tokens are short-lived by design and are cached only for their TTL. On AKS, the certificate inside the admin kubeconfig stays valid until the cluster’s certificates are rotated; ZopDay only holds it in memory and re-fetches it after 13 minutes. ZopDay mints new access when it needs the cluster again.

Space status

A registered space is either Active or Inactive. ZopDay keeps the status in step with the resources it discovers on your cloud account, rather than probing the cluster on a timer:

A newly registered space gets a 15-minute grace period before it can be marked inactive, so a slow first discovery doesn’t flag it. An inactive cluster becomes active again once it reappears in discovery and passes a live reachability check: being present proves the cluster exists, not that ZopDay can reach it.

Register a cluster

1. Grant cluster access (EKS only)

   Open Settings → Cloud Accounts, open the account’s actions menu and choose Manage Clusters. ZopDay lists the EKS clusters it finds in every region the account can see. Click Register on the cluster row. This calls:

   PUT /cloud-accounts/{accountID}/clusters/{region}/{clusterName}/access

   ZopDay creates an EKS access entry for its IAM principal and attaches AmazonEKSClusterAdminPolicy, so it can mint kubeconfigs later. GKE and AKS clusters skip this step.

2. Promote to a deployment space

   Open Infrastructure, select the discovered cluster and click Enable. ZopDay calls:

   POST /spaces

   …with the cluster identifier. ZopDay creates the deployment space, and the cluster shows as registered on Infrastructure.

The cluster is now ready to receive deploys.

Bind ZopDay in cluster RBAC

On EKS there is nothing to bind: Register in Manage Clusters already grants ZopDay’s IAM principal AmazonEKSClusterAdminPolicy through an EKS access entry. On GKE, bind ZopDay’s identity, the service-account email of the connected account, in your cluster’s Kubernetes RBAC. The recommended binding:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: zopday-deployer
subjects:
  - kind: User
    name: zopday@your-project.iam.gserviceaccount.com   # the connected account's service-account email
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: cluster-admin       # narrow this down for least privilege
  apiGroup: rbac.authorization.k8s.io

For least privilege, replace cluster-admin with a custom ClusterRole that grants only the verbs ZopDay needs in the namespaces it deploys to. Contact support for a least-privilege ClusterRole template. Most customers run cluster-admin for the first few months and tighten it later.

Deregister a cluster

Open the cluster from Infrastructure and click Remove Space. This:

1. Removes the deployment space and any namespace spaces under it (a soft delete, so it can be restored).
2. Does not revoke ZopDay’s cluster access. On EKS, do that separately: Settings → Cloud Accounts, Manage Clusters on the account, then Deregister on the cluster row.
3. Does not touch anything on the cluster itself; workloads keep running and manifests remain.
4. Does not delete dependent environments. Environments bound to this space can’t ship new deploys until you register the cluster again.

If you register the same cluster again later, ZopDay recognises it and restores the same space ID, so environments, deployments, attached registries, and custom domains that pointed at it line up again.

To remove cluster-side resources installed by ZopDay (Helm releases, secrets, ConfigMaps) before deregistering, either:

• Run helm uninstall on them from outside ZopDay.
• Trigger a full teardown per deployment from the UI, which removes everything ZopDay added.

Reference

Where a registered space appears

• Infrastructure: the Graph and List views show every cluster, VM, and datastore with its status, provider, region, and cost. In Graph view, clusters are grouped by cloud and region and linked to their datastores.
• Environment picker: when creating an environment inside a project, pick this space from the dropdown.
• Component installs: Helm components install onto this space as their own logged, retryable actions, not as provisioning jobs. See Components.

Troubleshooting

Next steps