Import a cluster

An existing customer-operated Kubernetes cluster with its control plane, nodes, and workloads sits on one side of a trust boundary; a kubeconfig stamped with scoped access crosses the boundary so an Akua workspace shows the cluster imported, with its nodes and workloads inventoried and a namespaces, deployments, and RBAC access scope

If you already have a Kubernetes cluster from any source, you can import it into Akua. This works with any existing cluster — whether it’s self-managed, from cloud providers (EKS, GKE, AKS), or other managed Kubernetes services. This lets you leverage your existing investment while gaining access to Akua’s product install and marketplace features. Consider creating a managed cluster instead if you don’t already have a Kubernetes cluster set up. Akua handles all the complex control plane management, so you can focus on your product rather than infrastructure operations. With imported clusters, control plane and worker operations are managed by your cloud provider or yourself, depending on your cluster type.

When to import versus create

Import your cluster
Create a managed cluster

Choose to import your cluster if you already have Kubernetes infrastructure from EKS, GKE, AKS, or other providers, have invested in cluster setup, need specific configurations like custom networking or , or want to maintain your existing cluster management approach.

Prerequisites

Before importing your cluster, ensure it meets these requirements:

Kubernetes version: 1.33+ (check with kubectl version)
Cluster access: Admin permissions, network connectivity, valid
Required permissions: management, workload deployment, operations

View detailed RBAC permissions

If you’re not using admin kubeconfig, create a service account with these permissions and bind it to a ClusterRole:

RBAC configuration

apiVersion: v1
kind: ServiceAccount
metadata:
  name: akua-sa
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: akua-role
rules:
  - apiGroups: ['']
    resources: ['pods', 'pods/log', 'pods/exec', 'secrets']
    verbs: ['get', 'list', 'watch', 'create', 'update', 'delete']
  - apiGroups: ['apps']
    resources: ['statefulsets', 'statefulsets/status']
    verbs: ['get', 'list', 'watch', 'create', 'update', 'delete']
  - apiGroups: ['']
    resources: ['namespaces', 'namespaces/finalize']
    verbs: ['get', 'list', 'watch', 'create', 'update', 'delete']
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: akua-role-binding
subjects:
  - kind: ServiceAccount
    name: akua-sa
roleRef:
  kind: ClusterRole
  name: akua-role
  apiGroup: rbac.authorization.k8s.io

How to import your cluster

Prepare your kubeconfig

Ensure you have a valid kubeconfig file with admin access to your cluster.

Test cluster connection

kubectl cluster-info
kubectl get nodes

Export kubeconfig

# If using default location
cat ~/.kube/config

# Or specify custom path
cat /path/to/your/kubeconfig

Navigate to the clusters dashboard

In the clusters dashboard, click “Import Cluster” and choose “Import Existing Cluster”.

Upload and validate kubeconfig

File upload
Paste content

Click “Upload kubeconfig file” and select your kubeconfig file.

Akua will automatically verify cluster accessibility, required permissions, Kubernetes version compatibility, and network connectivity.

If validation fails, check your kubeconfig and cluster permissions before retrying.

Configure and complete import

Set up how Akua will interact with your cluster: choose a cluster name, set the default namespace where new products will deploy, configure optional resource limits, and enable Akua observability (recommended). Then click “Import Cluster” to finalize the process.

Limitations of imported clusters

Be aware of these differences compared to managed clusters:

Control plane management

Control plane and worker operations are managed by your cloud provider or yourself, depending on your cluster type. Akua does not manage the control plane for imported clusters.

Worker node provisioning

You manage worker nodes yourself or through your cloud provider. Akua handles product installs but not worker infrastructure management.

Automatic updates

You must handle Kubernetes version updates and cluster maintenance yourself. Akua does not automatically update imported clusters.

Monitoring

Limited monitoring compared to managed clusters. Akua provides application-layer monitoring, but infrastructure monitoring is your responsibility.

Auto-scaling

Not supported through Akua. You must configure and manage auto-scaling through your cloud provider or cluster management tools.

Support level

Application layer support only. Akua helps with product installs and troubleshooting, but full infrastructure support is not included.

Troubleshooting

Kubeconfig validation fails

Verify cluster is accessible from the internet
Check that kubeconfig has admin permissions
Ensure Kubernetes version is 1.33 or newer
Test connection locally:

Test connection

kubectl cluster-info

Expected output

Kubernetes control plane is running at https://xxx.xxx.xxx.xxx:6443
CoreDNS is running at https://xxx.xxx.xxx.xxx:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Network connectivity issues

Verify cluster API server is publicly accessible
Check firewall rules allow Akua IP ranges
Ensure DNS resolution works for your cluster
Test from external network:

Test API server access

curl -k https://your-cluster-api:6443

Permission errors during import

Confirm kubeconfig has cluster-admin role
Check RBAC is properly configured
Verify service account has necessary permissions
Test permissions:

Test permissions

kubectl auth can-i "*" "*" --all-namespaces

Products failing to deploy

Check cluster has adequate resources
Verify default namespace exists and is accessible
Review cluster events:

Review events

kubectl get events --sort-by=.metadata.creationTimestamp

Contact support with deployment logs

API

Manage clusters programmatically.

Clusters API reference

Endpoints, parameters, response shapes, and try-it playground.

Authentication

Mint API tokens for programmatic access.

Create a managed cluster

Set up a cluster where Akua manages the control plane.

Clusters overview

Understand how clusters work in Akua.

Storage

Add persistent storage to your cluster.

Regions

Organize imported clusters with the rest of your infrastructure.

Clusters

Managed machines

Providers

Reference

When to import versus create

Prerequisites

How to import your cluster

Limitations of imported clusters

Troubleshooting

API

Clusters API reference

Authentication

Create a managed cluster

Clusters overview

Storage

Regions

​When to import versus create

​Prerequisites

​How to import your cluster

​Limitations of imported clusters

​Troubleshooting

​API

Clusters API reference

Authentication

​Related topics

Create a managed cluster

Clusters overview

Storage

Regions

When to import versus create

Prerequisites

How to import your cluster

Limitations of imported clusters

Troubleshooting

API

Related topics