Skip to main content

Access Clusters

This guide covers how to connect to Fluidstack managed Kubernetes clusters. You can use interactive authentication for local development, or ServiceAccount tokens for CI/CD automation.

Interactive Access with fluidctl​

To configure kubectl for access to a Fluidstack managed Kubernetes cluster, use the fluidctl auth update-kubeconfig command. This command automatically updates your local kubeconfig file with the necessary authentication credentials and cluster endpoint information.

You can find the pre-populated command with all required parameters on your cluster's page in the Atlas Dashboard. Simply navigate to your cluster and copy the provided command directly from the interface.

Command Syntax​

fluidctl auth update-kubeconfig --region <region> --project <project-id> --cluster-id <cluster-id>

The command requires three parameters: the region where your cluster is deployed, your project identifier, and the specific cluster ID you want to access. These values are unique to your deployment and determine which cluster configuration gets added to your kubeconfig.

Once executed, the command merges the cluster configuration into your existing ~/.kube/config file. The generated kubeconfig uses an exec-based credential plugin that automatically opens a browser for SSO authentication when you run kubectl commands. This requires an interactive terminal with browser access.

CI/CD Access with ServiceAccount Tokens​

For automation scenarios like CI/CD pipelines, GitHub Actions, or other headless runners where interactive browser authentication isn't possible, you can create a Kubernetes ServiceAccount with a long-lived token.

Configure your values:

Step 1: Create a ServiceAccount​

kubectl create serviceaccount ci-deployer -n <my-namespace>

Step 2: Create RBAC bindings​

Grant the ServiceAccount the necessary permissions. You can restrict the token's capabilities by choosing a different role:

  • view - Read-only access (list/get pods, logs, etc.)
  • edit - Deploy access (create/update/delete most resources, but not roles or bindings)
  • admin - Full namespace access including RBAC
  • Custom roles - Create your own Role for fine-grained control
# Example: grant deploy permissions in a specific namespace
kubectl create rolebinding ci-deployer-binding \
--clusterrole=edit \
--serviceaccount="<my-namespace>:ci-deployer" \
-n <my-namespace>

Step 3: Create a long-lived token Secret​

kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
name: ci-deployer-token
namespace: <my-namespace>
annotations:
  kubernetes.io/service-account.name: ci-deployer
type: kubernetes.io/service-account-token
EOF

Step 4: Retrieve the token and CA certificate​

TOKEN=$(kubectl get secret ci-deployer-token -n <my-namespace> -o jsonpath='{.data.token}' | base64 -d)
CA_CERT=$(kubectl get secret ci-deployer-token -n <my-namespace> -o jsonpath='{.data.ca\.crt}')

Step 5: Generate a kubeconfig file​

cat <<EOF > ci-deployer-kubeconfig.yaml
apiVersion: v1
kind: Config
clusters:
- name: <my-cluster>
cluster:
  server: https://<cluster-endpoint>:6443
  certificate-authority-data: $CA_CERT
contexts:
- name: ci-deployer@<my-cluster>
context:
  cluster: <my-cluster>
  user: ci-deployer
  namespace: <my-namespace>
current-context: ci-deployer@<my-cluster>
users:
- name: ci-deployer
user:
  token: $TOKEN
EOF

Step 6: Use in CI/CD​

kubectl --kubeconfig=ci-deployer-kubeconfig.yaml get pods

Alternatively, without a kubeconfig file:

echo $CA_CERT | base64 -d > ca.crt
kubectl --server=https://<cluster-endpoint>:6443 --token=$TOKEN --certificate-authority=ca.crt get pods
Security Considerations
  • ServiceAccount tokens are long-lived. If leaked, access persists until the token is manually revoked.
  • Store tokens securely in your CI/CD platform's secrets management (e.g., GitHub Secrets, GitLab CI Variables).
  • Use namespace-scoped permissions when possible to limit blast radius.
  • Consider rotating tokens periodically by deleting and recreating the Secret.