Access and kubectl

Everything you need to reach the cluster sits in a kubeconfig that you download from the portal. It already points at the right API endpoint, so there is nothing to configure by hand.

Download the kubeconfig

You find it in the Kubernetes section of the portal, where you download the kubeconfig for your namespace as a file. If you have several namespaces, each one has its own kubeconfig.

A kubeconfig is a credential

It is full access to your namespace. Treat it like a password: not in a repository, not attached to a ticket, not pasted into a chat.

Where to put the file

If you do not use any other cluster, ~/.kube/config is the simplest option. Replace the source path with the one your browser downloaded to:

mkdir -p ~/.kube
mv ~/Downloads/kubeconfig.yaml ~/.kube/config
chmod 600 ~/.kube/config

If you work with several clusters, keep it as its own file and point KUBECONFIG at it instead:

mv ~/Downloads/kubeconfig.yaml ~/.kube/itsh.yaml
chmod 600 ~/.kube/itsh.yaml
export KUBECONFIG=~/.kube/itsh.yaml

KUBECONFIG also takes several files separated by colons. kubectl merges them, and you switch between clusters with kubectl config use-context:

export KUBECONFIG=~/.kube/config:~/.kube/itsh.yaml

Put that line in your shell configuration, otherwise it only applies to the current session.

To check which context kubectl is currently working in:

kubectl config current-context

Set the default namespace

Your kubeconfig is valid for exactly one namespace, but kubectl does not assume that. Set it as the default once:

kubectl config set-context --current --namespace=<your-namespace>

The namespace name is shown in the portal next to the kubeconfig. Without this step you have to append -n <your-namespace> to every command, otherwise it runs against the namespace default, which you have no access to.

First check

kubectl get pods

On an empty namespace kubectl answers with No resources found in <your-namespace> namespace. That is the success case: authentication worked, there is simply nothing to show yet.

From here, continue with Your first deployment.

Your access stops at your namespace

The kubeconfig is scoped to your own namespace only. There is no cluster-wide read, not even for objects that look harmless:

Error from server (Forbidden): nodes is forbidden: User "..." cannot list
resource "nodes" in API group "" at the cluster scope

That is not a broken setup, it is the intended behaviour.

When a command returns Forbidden

Three causes are likely, in this order:

1. The default namespace is not set and the command runs against default. kubectl config view --minify shows which namespace the current context carries.
2. The resource is not among the ones your namespace may touch. What is granted is listed under Permissions and policies.
3. KUBECONFIG still points at another cluster. kubectl config current-context tells you where you are.

Validity and replacement

A kubeconfig is valid for one year from the moment you download it. After that every command using it fails to authenticate. You get an email before it expires; nothing warns you inside a script or a pipeline, so if you use a kubeconfig for automation, put the renewal in your own calendar.

Downloading again from the portal gives you a fresh file with a fresh year. You can do that whenever you like, and as often as you like.

A new download does not disable the old file

Each download issues an additional independent credential. It does not replace or revoke the ones you already have, and there is no way to switch an old kubeconfig off yourself.

So if a kubeconfig leaks, downloading a new one does not contain the leak. The old file keeps working for the rest of its year. Contact support, who can cut off access to the namespace.

Because of that, treat the file as a long-lived credential: keep it out of repositories, tickets and chat, store it somewhere with access control, and hand it to automation as a secret rather than as a file in a checkout.

What's next

• Your first deployment to get something running
• Permissions and policies for what you may create