create_aws_cluster
Create and provision a new self-managed Kubernetes cluster on AWS EC2: k3s or kubeadm on Ubuntu instances reached through a bastion host, with the AWS cloud controller manager, the EBS CSI driver and an NLB-fronted ingress installed. By default Ankra creates the network: a VPC from network_ip_range (default 10.0.0.0/16) with a public /24 and a private /20 per availability zone, an internet gateway and NAT gateways (egress_mode nat_gateway), all torn down with the cluster; omit vpc_id for this and, unless the user names availability_zones, the preflight picks one zone (three when control_plane_count is 3 or more). To adopt an existing VPC instead, pass vpc_id with at least one private node subnet (node_subnet_ids) and a public bastion subnet (bastion_subnet_id); Ankra never modifies an adopted VPC's network. Requires an AWS credential, an SSH key credential, a region and the IPv4 CIDRs allowed to SSH to the bastion. Use list_provider_credentials with provider='aws' and provider='ssh-key' to find the credential ids. There is no chat-side VPC or subnet listing: when adopting, take the vpc_id, node_subnet_ids and bastion_subnet_id from the user (or the AWS console) and confirm with them, before proposing, that every subnet belongs to that VPC and region, the node subnets are private, and the bastion subnet routes to an internet gateway - the same checks the create's preflight enforces. The create runs that preflight first (credential scope; for a created network the CIDR plan, the zones and the VPC / NAT-gateway / elastic-IP quotas, for an adopted VPC the VPC and subnet facts and egress routes; instance-type availability, service quotas) and refuses with every failing item when it cannot proceed; nothing is written on refusal. Instance types are EC2 names (e.g. 't3.medium', 'm6i.large'). Managed EKS creation is create_managed_cluster, not this tool. Only available to organisations with AWS self-managed provisioning enabled.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cni | No | Container network plugin. Default: 'cilium'. Cilium and Calico enforce the IMDS guard (the network policy that keeps pods off the instance metadata service and the node's instance role); flannel cannot enforce it, so a flannel cluster is accepted with a warning that pods on control-plane nodes can reach the control-plane instance role. | |
| name | Yes | Cluster name. Must be unique within the organisation. | |
| region | Yes | AWS region the cluster (and its VPC) lives in (e.g., 'eu-west-1', 'us-east-1'). | |
| vpc_id | No | Id of an existing VPC to adopt (e.g., 'vpc-0abc...'); node_subnet_ids and bastion_subnet_id are then required and network_ip_range, availability_zones and nat_gateway_single_zone are refused. Omit it to have Ankra create the VPC and its subnets. | |
| description | No | Optional cluster description. | |
| egress_mode | No | How the private node subnets reach the internet. Created VPC: 'nat_gateway' (default; Ankra-created NAT gateways with their own elastic IPs) or 'bastion_nat' (the bastion is the NAT instance); 'existing' is refused. Adopted VPC: 'existing' uses the subnets' own NAT gateway or egress route, 'bastion_nat' makes the bastion the NAT for them, 'nat_gateway' is refused (it would re-point the customer's route tables); omit to let the preflight resolve it from the subnets' route tables. | |
| include_dns | No | Provision the cluster's Ankra-managed DNS zone. Default: true. | |
| worker_type | No | EC2 instance type for worker nodes. Default: 't3.medium'. | |
| distribution | No | Kubernetes distribution. Default: 'kubeadm' (vanilla upstream Kubernetes with Cilium). 'k3s' is the lightweight alternative. kubeadm supports only the cilium CNI on AWS. | |
| worker_count | No | Number of worker nodes. Default: 1. | |
| credential_id | Yes | UUID of the AWS credential. Get from list_provider_credentials with provider='aws'. A role credential must have been onboarded with the 'provisioning' or 'self_managed' scope; an access-keys credential is accepted and the preflight probes decide. | |
| gitops_branch | No | Branch of the GitOps repository. Default: 'master'. | |
| ubuntu_series | No | Ubuntu LTS series for the node image, resolved from Canonical's public AMI catalogue (e.g., '24.04'). Default: '24.04'. | |
| gitops_provider | No | Provider of the GitOps repository: 'github' (the default when omitted) or 'bitbucket_cloud'. Pass the credential's provider from list_gitops_credentials. | |
| node_subnet_ids | No | Adopted VPC only: private subnet ids (e.g., 'subnet-0abc...') in the VPC for the control-plane and worker nodes; at least one, spread across availability zones for HA. They must not route to an internet gateway. Refused without vpc_id - a created VPC lays out its own subnets. | |
| root_volume_gib | No | Root volume size in GiB for every node (gp3). Default: 40. | |
| gitops_repo_slug | No | Bitbucket Cloud repository slug of the GitOps repository (from list_gitops_repositories). Only with gitops_provider 'bitbucket_cloud', together with gitops_workspace. | |
| gitops_workspace | No | Bitbucket Cloud workspace of the GitOps repository (from list_gitops_repositories). Only with gitops_provider 'bitbucket_cloud', together with gitops_repo_slug. | |
| network_ip_range | No | Created VPC only: the IPv4 CIDR the VPC is created with, /16 to /20 as a network address (default '10.0.0.0/16'); it must hold a private /20 and a public /24 per availability zone. Refused alongside vpc_id. | |
| retention_policy | No | Storage retention on teardown. Default: 'retain'. | |
| bastion_subnet_id | No | Adopted VPC only: public subnet id in the VPC for the bastion host; it must route to an internet gateway so the bastion gets a reachable public address. Refused without vpc_id. | |
| gitops_repository | No | Optional GitOps repository to connect at creation: 'owner/repo' on GitHub, 'workspace/repo_slug' on Bitbucket Cloud; requires gitops_credential_name. | |
| availability_zones | No | Created VPC only: the zones the VPC is laid out over, in order (the bastion and the first control plane land in the first), e.g. ['eu-west-1a', 'eu-west-1b', 'eu-west-1c']. More than one zone needs control_plane_count >= 3. Omit to let the preflight pick one zone (three when control_plane_count >= 3) from the region's available zones. Refused alongside vpc_id. | |
| control_plane_type | No | EC2 instance type for control plane nodes. Default: 't3.medium'. | |
| include_networking | No | Install the platform networking stack (ingress, cert-manager, external-dns). Default: true. | |
| kubernetes_version | No | Kubernetes version. If not specified, uses the latest supported version. | |
| bastion_allowed_ips | Yes | IPv4 CIDRs allowed to SSH to the bastion (e.g., '203.0.113.4/32'); IPv6 is accepted only as the open-world '::/0', and any other IPv6 CIDR is refused. Required: name at least one, or the call is refused. '0.0.0.0/0' (and '::/0') is accepted rather than refused - it leaves SSH reachable from the whole internet, where access is still key-only with password login off and sshd rate-limited on the host. Preflight reports the exposure either way in bastion_ssh_exposure: a warning when the list is open, ok when it is narrowed. Name the operator's own CIDRs to restrict it. | |
| control_plane_count | No | Number of control plane nodes. Default: 1. | |
| bastion_instance_type | No | EC2 instance type for the bastion host. Default: 't3.small'. | |
| ssh_key_credential_id | Yes | UUID of the SSH key credential. Get from list_provider_credentials with provider='ssh-key'. | |
| gitops_credential_name | No | Name of the git credential, GitHub or Bitbucket Cloud, that can read the GitOps repository (see list_gitops_credentials). Requires gitops_repository, or for Bitbucket Cloud gitops_workspace and gitops_repo_slug. | |
| nat_gateway_single_zone | No | Created VPC with nat_gateway egress only: true creates one NAT gateway in the first zone that every private subnet routes through (cheaper, one egress failure domain) instead of one per zone. Default: false. Refused when true alongside vpc_id. |