cub cluster attach

Wire a cluster you already have into ConfigHub via Argo CD

Synopsis

Attaches a cluster you already have — any cluster your kubeconfig can reach with cluster-admin — into ConfigHub. It is everything "cub cluster up" does after creating its kind cluster, and "cub cluster up" is built on it.

Attach never creates or destroys a cluster. The inverse, "cub cluster detach", removes the wiring and leaves the cluster running.

Where the cluster's credentials come from is --provider:

kubeconfig (default) your kubeconfig — $KUBECONFIG or ~/.kube/config, or --kubeconfig — at its current context, or the one --kube-context names. eks the AWS CLI: "aws eks update-kubeconfig" for the cluster named by --cluster (defaults to the cluster name), honoring --aws-region and --aws-profile or the usual AWS environment. The kubeconfig authenticates through the CLI, so it stays good as long as your AWS credentials are. kind a kind cluster already on this machine, named by --cluster (defaults to the cluster name), through "kind get kubeconfig". "cub cluster up" is the command that creates one and attaches it.

A self-contained copy of the credentials is written to /clusters/.kubeconfig, beside a record of which ConfigHub server and organization the cluster is wired to, so "cub cluster list", "open" and "down" find it whichever cub context is current. A kubeconfig with a static token that expires, expires in the copy too.

An EKS cluster created by something other than you — an ACK controller, a pipeline role — grants its bootstrap admin access to that identity, and rejects you with a bare 401. Attach diagnoses that: if your AWS identity has no access entry on the cluster it prints the commands that add one, or runs them for you with --grant-access (an access entry with the AmazonEKSClusterAdminPolicy).

What it sets up, in the cluster:

Argo CD installed from the upstream manifest if the argocd namespace has no argocd-server; an existing Argo CD is left as found (--no-argocd fails instead of installing). Either way argocd-cm gets the ignoreDifferences block the self-referencing root Application needs, unless it already carries one. repo-creds Secret a long-lived token of the cluster's service account, so Argo CD can pull from ConfigHub's OCI registry. root Application bootstrapped once with kubectl; from then on Argo pulls everything else from ConfigHub. argobot unless --no-argobot: a bot that listens on a Channel and force-syncs the matching Argo Application the moment a deploy happens, instead of waiting for Argo's poll, and reports each Release's live status back.

And in ConfigHub:

the cluster Space: an OCI target that represents the cluster, and argobot's Channel. A pure namespace — it holds no config bundle. -argo-apps the apps Space: the root "app of apps" Application Unit and every child Argo Application Unit. Its release target is the OCI target in the cluster Space, so the apps Space is the config bundle Argo pulls. argo- a service account with no organization role, the cluster's identity: the target grants its user View, ViewChildren and EditChildren; Argo CD pulls with a token of it and argobot runs as it with a key.

The OCI target is gated: a "no-placeholders" Trigger in the cluster Space blocks publishing a Release that still contains an unfilled "confighubplaceholder" value, for every Space that releases to this cluster. Pass --no-placeholder-gate to skip the Trigger; the target is wired either way.

A cluster is wired to one ConfigHub at a time: attach refuses a cluster whose Argo CD already holds ConfigHub registry credentials, and a remote cluster against a ConfigHub on localhost, which Argo inside the cluster could never reach.

Argo CD is not exposed outside the cluster by attach. Reach its UI with "kubectl port-forward svc/argocd-server -n argocd 8080:80" against the kubeconfig attach wrote; the initial admin password is in argocd-initial-admin-secret.

Examples: # Attach whatever your current kube context points at cub cluster attach staging

# Attach a named context from a specific kubeconfig cub cluster attach prod-eu --kubeconfig ~/.kube/eu.yaml --kube-context prod-eu

# Attach a cluster that already runs Argo CD, without argobot cub cluster attach shared --no-argocd --no-argobot

# Attach an EKS cluster of the same name, granting yourself cluster-admin first cub cluster attach inference-demo --provider eks \ --aws-region us-west-2 --aws-profile cubdev --grant-access

# Attach a kind cluster you created by hand cub cluster attach lab --provider kind

cub cluster attach <name> [flags]

Options

      --argobot-oci string      OCI reference of argobot's config bundle, or a local file or directory of its manifests (default "oci://ghcr.io/confighub/configs/argobot")
      --argocd-version string   Argo CD release to install when absent (v3.1 or later; oci:// sources need it) (default "stable")
      --aws-profile string      --provider eks: the AWS CLI profile (defaults to AWS_PROFILE)
      --aws-region string       --provider eks: the cluster's AWS region (defaults to the AWS CLI's: AWS_REGION or the profile's)
      --cluster string          the cluster's name at the provider (--provider eks or kind; defaults to the cluster name)
      --controller string       controller to wire to ConfigHub: argo (Argo CD); sveltos and flux are not supported by attach yet (default "argo")
      --grant-access            --provider eks: if your AWS identity has no access entry on the cluster, add one with cluster-admin
  -h, --help                    help for attach
      --kube-context string     --provider kubeconfig: the kube context to attach (defaults to the kubeconfig's current context)
      --kubeconfig string       --provider kubeconfig: the kubeconfig to read the cluster from (defaults to $KUBECONFIG or ~/.kube/config)
      --no-argobot              skip installing argobot (the event-driven Argo CD sync bot)
      --no-argocd               never install Argo CD; fail if the cluster has none
      --no-placeholder-gate     skip the default vet-placeholders Trigger, allowing Releases with unfilled confighubplaceholder values to be published to this cluster
      --provider string         where the cluster's credentials come from: kubeconfig, eks or kind (default "kubeconfig")
      --space string            ConfigHub space slug for the cluster's target and argobot channel (the "target prefix"); the apps space is this slug + "-argo-apps" (defaults to <name>)

Options inherited from parent commands

      --context string   The context to use for this command
      --debug            Debug output

cub cluster attach