Connect to your cluster

Use your provided kubeconfig, select the right context and verify namespace permissions safely.

GuideTechnical reference · not required for Cloud UIReading time · approx.7 minutesUpdated22 October 2026

Availability of this guideEnterprise reference

For Enterprise Self-Hosted or a separately agreed technical evaluation. Not a Cloud customer procedure.

Before you start

A pilot cluster must already have been provided. Obtain the kubeconfig and namespace through the agreed secure channel. Install a kubectl client compatible with the delivered Kubernetes version. Use only a kubeconfig from a trusted source; it may contain credentials or executable authentication configuration.

1. Select the cluster explicitly

Replace every YOUR_ value and the file path below with your handover details. In a POSIX shell, KUBECONFIG selects the file for this session. The context and namespace flags on later commands keep each request scoped. The commands below do not overwrite your normal kubeconfig or change its current context.

POSIX · kubeconfig / context / namespace

export KUBECONFIG="/absolute/path/to/pilot-kubeconfig.yaml"
chmod 600 "$KUBECONFIG"
kubectl version --client
kubectl --kubeconfig="$KUBECONFIG" config get-contexts
export CP_CONTEXT="YOUR_CONFIRMED_CONTEXT"
export CP_NAMESPACE="YOUR_ASSIGNED_NAMESPACE"

On Windows PowerShell, set the same session variables as shown below. Protect the kubeconfig with your operating system's file permissions; chmod is not a PowerShell step.

PowerShell · kubeconfig / context / namespace

$env:KUBECONFIG = "C:\secure\pilot-kubeconfig.yaml"
kubectl --kubeconfig="$env:KUBECONFIG" config get-contexts
$CP_CONTEXT = "YOUR_CONFIRMED_CONTEXT"
$CP_NAMESPACE = "YOUR_ASSIGNED_NAMESPACE"

2. Check access before making changes

Use the POSIX block below in the same terminal where you set the three variables. The surrounding parentheses keep a missing-setting error from continuing the pasted block or closing your terminal. Replace the YOUR_ placeholders before this check.

Read-only access checks · POSIX

(
: "${KUBECONFIG:?Set KUBECONFIG from your handover}"
: "${CP_CONTEXT:?Set CP_CONTEXT from your handover}"
: "${CP_NAMESPACE:?Set CP_NAMESPACE from your handover}"
case "$CP_CONTEXT:$CP_NAMESPACE" in
  YOUR_*|*:YOUR_*) printf '%s\n' 'Replace the YOUR_ context and namespace placeholders first.' >&2; exit 1 ;;
esac
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" auth can-i list pods
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" auth can-i get pods
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" auth can-i get pods --subresource=log
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" auth can-i create deployments.apps
kubectl --kubeconfig="$KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" get pods
)

PowerShell access check (the subsequent workload guides use POSIX syntax):

PowerShell · kubectl

& {
if (-not $env:KUBECONFIG -or -not $CP_CONTEXT -or -not $CP_NAMESPACE) { throw "Set the handover variables first." }
if ($CP_CONTEXT -like "YOUR_*" -or $CP_NAMESPACE -like "YOUR_*") { throw "Replace the YOUR_ placeholders first." }
kubectl --kubeconfig="$env:KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" auth can-i list pods
kubectl --kubeconfig="$env:KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" auth can-i get pods
kubectl --kubeconfig="$env:KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" auth can-i get pods --subresource=log
kubectl --kubeconfig="$env:KUBECONFIG" --context="$CP_CONTEXT" --namespace="$CP_NAMESPACE" get pods
}

Expect yes for the reads needed by your role. Creation rights are only expected when the pilot grants application deployment access. An empty Pod list can be normal in a fresh namespace. Cluster-wide node listing or cluster-admin access is not a prerequisite for these customer guides.

3. Recognize the failure boundary

Signal	Next check
Unauthorized	Check credential expiry and the agreed authentication method; request a secure refresh.
Forbidden	Confirm the context, namespace, requested operation and assigned role.
Timeout / connection refused	Confirm endpoint, network access requirements and current service status with the operator.
x509 / certificate	Check local time and the supplied endpoint/CA details. Share the error text without the kubeconfig.

Troubleshoot common failures →

4. Handle access changes deliberately

Keep the access file out of Git, chat transcripts and ticket attachments. Use an individual identity where the agreed access method supports it. Define who requests revocation when a teammate leaves or a device is lost. Credential rotation and team administration capabilities must be confirmed for the pilot; no Cloud account UI is assumed here.

Deploy your first application →

Technical references

These Kubernetes references describe technical behavior. Your pilot agreement defines the capabilities confirmed for your cluster.

Use this guide within your agreed pilot scope. Kubernetes examples are not evidence of a generally available Cloud capability.