Access with kubectl

Point kubectl at any cluster AstroPulse manages: EKS, GKE, AKS or registered. The kubeconfig holds no token, certificate or cloud session: kubectl runs astroctl to get a short-lived token, so you need astroctl signed in on your machine and nothing from your cloud. A self-hosted cluster gets a kubeconfig with its own client certificate instead (Self-hosted clusters), and --native signs in with your own cloud identity (below).

Before you start

• astroctl installed and signed in on the machine that runs kubectl: the setup guide. A self-hosted cluster's certificate kubeconfig and a --native kubeconfig do not run astroctl.
• An org admin role. The organization owner counts as one; other members are refused with Insufficient organization permissions.
• A plan with role-based access.

In the console

1. Open the cluster from the cluster list and select the Access tab: "Connect kubectl to <cluster>."

2. With astroctl (marked Recommended): "Install it and sign in once, then point kubectl at this cluster. No file to keep safe." Copy the three commands and run them: install astroctl, sign in, and astroctl infra k8s set-context --cluster-name <cluster-name>.

3. Or With a kubeconfig file: pick Valid for, then select Generate. "Save it now. It won't be shown again." Select Download, then use it with export KUBECONFIG=./<cluster-name>-kubeconfig.yaml. Generate new makes another.

   Open zoom view

   The Access tab: With astroctl, marked Recommended, and With a kubeconfig file with its lifetimes and Generate

   

The downloaded file still runs astroctl to sign in, so astroctl must be installed and signed in wherever you use it.

You should see

Terminal

kubectl get nodes

lists the cluster's nodes.

How access works

The kubeconfig holds no token, certificate or cloud session. kubectl runs astroctl as a credential plugin:

YAML

users:
- name: <cluster-name>
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      command: astroctl
      args: ["infra", "k8s", "access-token", "--cluster-name", "<cluster-name>"]
      interactiveMode: Never

astroctl infra k8s access-token returns a short-lived token, and astroctl renews it on its own five minutes before it expires. kubectl keeps working with no step from you until the duration ends.

One end time per cluster. You have one end time on each cluster for all your kubeconfigs that renew through AstroPulse. Generating a kubeconfig, from the console or astroctl, sets that end time for all of them, shorter included: a 1 hour kubeconfig from the console ends a 24 hour one from your terminal at the same moment. A file someone else generated works only while you have an end time of your own on that cluster.

Who the cluster sees. On a cluster AstroPulse created, kubectl acts as the identity AstroPulse uses for that cluster, so every admin gets the same rights and the cluster's own logs do not name the person. Audit Logs (Enterprise plan) record who asked for each token, as a Credential event.

Organization. The token is issued in the organization astroctl is using when kubectl runs it. After astroctl org use to another organization, kubectl is refused for this cluster until you switch back.

Ending someone's access. Remove them from the organization, or lower their role below admin. That stops new tokens at once; a token already issued runs to its own expiry. No command ends a running duration. If access must end at an exact moment, remove the access of the identity AstroPulse uses for the cluster; that also stops everyone else's kubectl, and AstroPulse itself, until you restore it.

Sign in with your own cloud identity

Add --native to generate-kubeconfig. The kubeconfig then runs your cloud's tool, carries no AstroPulse session and has no duration.

Cluster	You need
EKS	AWS CLI v2 signed in to the account, and an EKS access entry for your IAM identity on the cluster
GKE	Google Cloud CLI with gke-gcloud-auth-plugin, gcloud auth login, and an IAM role on the project such as Kubernetes Engine Developer
AKS	Azure CLI signed in (az login), kubelogin, and an Azure RBAC role on the cluster such as Azure Kubernetes Service RBAC Cluster Admin
Self-hosted, registered	Not available. Generate without --native.

--native on a self-hosted or registered cluster is refused; see If it's refused.

Self-hosted clusters

A self-hosted cluster's kubeconfig holds its own client certificate instead of running astroctl, and is generated in the background:

Terminal

astroctl infra k8s generate-kubeconfig --cluster-name <cluster-name> --duration 4h
astroctl infra k8s set-context --cluster-name <cluster-name>   # once it is ready, after a few minutes

The certificate lasts for the duration you chose. When it expires, generate a new one.

Other ways in

• Nova: ask "how do I get kubectl access to prod-eks?" and Nova returns the astroctl command to run on your machine.
• SDK and API: generate a kubeconfig for a cluster, and the access token kubectl uses. See the API reference.

With astroctl

Terminal

astroctl infra k8s generate-kubeconfig --cluster-name <cluster-name> --duration 4h
kubectl get nodes

This writes the kubeconfig to the file $KUBECONFIG names (its first file) if it is set, else ~/.kube/config, and switches kubectl to it:

Kubeconfig generated and saved for cluster: <cluster-name>
This kubeconfig works for 4h, until <UTC time>; its access renews on its own until then. Your other kubeconfigs for this cluster that renew through AstroPulse now end then too. Generate a new one after that.
Written to <path>
kubectl context switched to "<context>" (was "<previous>")
Switch back with: kubectl config use-context <previous>
You can now use kubectl to access your cluster

With no earlier context, the two switched lines are instead kubectl is now using context "<context>".

astroctl infra k8s set-context --cluster-name <cluster-name> writes the same kubeconfig without choosing a duration: it starts the default hour if you have none running, and never shortens one you have.

To remove the cluster from your kubeconfig:

Terminal

astroctl infra k8s delete-context --cluster-name <cluster-name>

Settings

Valid for--duration

How long kubectl keeps access through this kubeconfig.

Accepts

1h, 4h, 12h or 24h.

Default

1h

--native

Sign in with your own cloud identity through your cloud's tool, instead of AstroPulse.

Default

Off.

See

Sign in with your own cloud identity

If it's refused

kubectl prints each message as sent.

Access to cluster <cluster> through this kubeconfig has ended. Generating a kubeconfig sets one end time for all your kubeconfigs on a cluster that renew through AstroPulse. followed by the command to run

Cause

Your end time on this cluster passed.

Fix

Run astroctl infra k8s generate-kubeconfig --cluster-name <cluster-name>.

cannot get an AstroPulse access token for cluster <cluster>: followed by the reason

Cause

astroctl could not get a token. With Insufficient organization permissions, you are not an org admin.

Fix

Run astroctl auth login and astroctl infra k8s get --cluster-name <cluster-name>. For a permissions refusal, ask an org owner for the admin role.

cannot get an AstroPulse access token for cluster <cluster>: followed by Role-Based Access Control needs the <plan> plan; your organization is on <your plan>. See https://astropulse.io/pricing

Cause

Your plan does not include kubectl through AstroPulse.

Fix

Upgrade your plan.

Cluster access is not available right now. Try again in a moment.

Cause

AstroPulse cannot record or read your end time, so it refuses rather than guess.

Fix

Try again shortly.

exec: executable astroctl not found

Cause

astroctl is not on this machine's PATH.

Fix

Install astroctl and put it on PATH.

unknown command or unknown flag: --cluster-name from astroctl

Cause

The astroctl kubectl runs is older than this kubeconfig.

Fix

Run astroctl update, then astroctl infra k8s set-context --cluster-name <cluster-name>.

Unauthorized from a cluster AstroPulse created

Cause

The identity AstroPulse uses for the cluster has lost its access, such as its access entry on EKS.

Fix

Restore that access in your cloud account.

Registered clusters: NotFound: No cluster is reachable at this address with this credential. If this kubeconfig is from an older astroctl, run astroctl infra k8s set-context --cluster-name <cluster> to refresh it.

Cause

The request carried no valid token for this cluster: an unknown cluster, one in another organization, or a kubeconfig from an older astroctl.

Fix

Run astroctl update, then astroctl infra k8s set-context --cluster-name <cluster-name>. Check that astroctl whoami shows the organization that owns the cluster.

Registered clusters: Unauthorized: Your AstroPulse access to this cluster has expired. kubectl gets a new access token on its next request; if this keeps happening, run astroctl infra k8s set-context --cluster-name <cluster> to refresh this kubeconfig.

Cause

The token expired.

Fix

Run the kubectl command again. If it repeats, run astroctl infra k8s set-context --cluster-name <cluster-name>.

Registered clusters: ServiceUnavailable: The cluster's agent has not reported its credential yet, so the request cannot be sent. Try again in a minute; if this persists, check the agent with astroctl infra k8s get --cluster-name <cluster>.

Cause

The agent in the cluster has not reported to AstroPulse yet.

Fix

Wait a minute and retry. If it persists, run astroctl infra k8s get --cluster-name <cluster-name> and check the agent.

"Cluster <cluster> is self-hosted: its API has no cloud provider sign-in, so there is no native kubeconfig. Generate its kubeconfig without the native option for one with its own client certificate."

Cause

--native was used on a self-hosted cluster.

Fix

Generate the kubeconfig without --native.

"Cluster <cluster> is reached only through AstroPulse: it has no cloud provider sign-in of its own. Generate its kubeconfig without the native option."

Cause

--native was used on a registered cluster.

Fix

Generate the kubeconfig without --native.

Next

• Update and upgrade
• Audit logs