Morpheus Clusters - Ankra Platform

Ankra supports provisioning fully managed Kubernetes clusters through Morpheus. Ankra provisions instances via your Morpheus appliance using the groups, clouds, networks, virtual images, and service plans you already manage there - then installs Kubernetes and manages the full cluster lifecycle: node groups, scaling, upgrades, and deprovisioning.

Closed beta. Morpheus cluster provisioning is in closed beta. The workflow is stable but the surface may still change, and it is enabled per organisation on request. Contact support to have it turned on for your organisation.

Prerequisites

Before creating a Morpheus cluster, you need two credentials:

Morpheus API Credential

The Morpheus appliance URL and a long-lived API access token. See Morpheus Credentials.

SSH Key Credential

An SSH public key for instance access. You can provide your own or let Ankra generate one. See SSH Key Credentials.

Your Morpheus environment must also provide:

A group and cloud the API token can provision into.
A network with DHCP. Cluster instances get their addresses from DHCP on the network you select.
An instance layout based on a Linux cloud image, used for all cluster instances. You can optionally pin a specific virtual image.
Service plans to size the bastion, control plane, and worker instances.
API reachability. The Morpheus API must be reachable from Ankra either directly or through an SSH jumphost.

Hybrid Connectivity (SSH Jumphost)

If the Morpheus appliance and the instance network are not directly reachable from Ankra, attach an SSH jumphost (host, port, username, and private key) to your Morpheus credential. Ankra then tunnels both the Morpheus API calls and the SSH connections to your cluster nodes through the jumphost. If your Morpheus appliance uses a self-signed certificate, enable the TLS insecure toggle (tls_insecure) on the credential. Both options are configured on the credential - see Morpheus Credentials.

Creating a Morpheus Cluster

Via the Platform UI

Navigate to Clusters

Go to Clusters in the Ankra dashboard and click Create Cluster.

Select Morpheus

Choose Morpheus as the provider.

Select Credentials

Pick your Morpheus API credential and SSH key credential from the dropdowns. You can also create new credentials directly from the wizard.

Choose Placement

Select the Morpheus group, cloud, and network for the cluster instances, and the instance layout (based on a Linux cloud image) they are provisioned from. The network must provide DHCP.

Configure Nodes

Set your cluster topology using Morpheus service plans as instance types:

Bastion - Service plan for the SSH bastion instance
Control Plane - Count (1 or 3) and service plan
Workers - Count and service plan

The wizard shows the vCPUs and memory of each service plan. Cost estimates are not available for Morpheus clusters.

Choose Distribution

Pick the Kubernetes distribution: k3s Lightweight Kubernetes with a user-selectable CNI (default). kubeadm Vanilla upstream Kubernetes bootstrapped with kubeadm and containerd. kubeadm clusters always use Cilium CNI and optionally support an external etcd topology with dedicated etcd instances.See Kubernetes Distribution for details.

Create & Track Progress

Click Create to start provisioning. A live progress view tracks credential setup, SSH key deployment, bastion provisioning, instance creation, Kubernetes installation (k3s or kubeadm), and Ankra Agent setup. The cluster appears with an offline state until provisioning completes, then transitions to online.

Via the API

Morpheus clusters are managed from the portal or API during the closed beta - the ankra CLI does not yet include Morpheus commands. Create the Morpheus credential and SSH key credential from the portal first.

curl -X POST https://platform.ankra.app/api/v1/clusters/morpheus \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-cluster",
    "credential_id": "<morpheus-credential-id>",
    "ssh_key_credential_id": "<ssh-key-credential-id>",
    "group_id": 1,
    "cloud_id": 1,
    "network_id": 2,
    "layout_id": 42,
    "bastion_plan_id": 101,
    "control_plane_count": 1,
    "control_plane_plan_id": 102,
    "node_groups": [
      {"name": "default", "plan_id": 102, "count": 2}
    ],
    "distribution": "k3s"
  }'

Cluster Configuration Options

All Morpheus IDs are the numeric IDs from your appliance - discover them in the portal’s create wizard or with the catalog API routes (groups, clouds, networks, layouts, plans).

Parameter	Default	Description
`name`	required	Unique cluster name
`credential_id`	required	Morpheus API credential ID
`ssh_key_credential_id`	required	SSH key credential ID
`group_id`	required	Numeric ID of the Morpheus group to provision into
`cloud_id`	required	Numeric ID of the Morpheus cloud to provision into
`network_id`	required	Numeric ID of the Morpheus network the instances attach to (must provide DHCP)
`layout_id`	required	Numeric ID of the instance layout the instances are provisioned from
`virtual_image_id`		Numeric ID of a virtual image to pin (optional; the layout’s image is used otherwise)
`bastion_plan_id`	required	Numeric service plan ID for the bastion instance
`control_plane_count`	`1`	Number of control plane nodes (1, 3, or 5)
`control_plane_plan_id`	required	Numeric service plan ID for control planes
`worker_count`	`1`	Number of worker nodes (legacy, use `node_groups` instead)
`worker_plan_id`	required	Numeric service plan ID for workers
`node_groups`		Array of node group definitions sized by numeric `plan_id` (see Node Groups)
`distribution`	`k3s`	Kubernetes distribution (`k3s` or `kubeadm`)
`kubernetes_version`	latest stable	Kubernetes version (optional)
`cni`	`flannel` (k3s)	CNI plugin. kubeadm clusters always use `cilium`
`etcd_topology`	`stacked`	kubeadm only. `stacked` (etcd on control planes) or `external` (dedicated etcd instances)
`etcd_node_count`	`3`	kubeadm `external` topology only. Number of dedicated etcd instances (3 or 5)
`etcd_plan_id`		kubeadm `external` topology only. Numeric service plan ID for dedicated etcd nodes

Cost estimates are not available for Morpheus clusters - neither in the creation wizard nor in Cloud Cost.

Networking

Ankra does not create networks in Morpheus. You select an existing network at creation, and all cluster instances receive their IP addresses via DHCP on that network. Make sure DHCP is available before creating the cluster.

Kubernetes Distribution

Morpheus clusters can be provisioned with either k3s (default) or kubeadm.

	k3s	kubeadm
Kubernetes	Lightweight, single-binary distribution	Vanilla upstream Kubernetes
CNI	User-selectable (Flannel default)	Cilium (fixed, cannot be changed after creation)
etcd	Embedded	`stacked` (on control planes) or `external` (dedicated instances)
Version format	`v1.35.1+k3s1`	`v1.31.0` (plain upstream tag)

kubeadm clusters always use Cilium CNI (eBPF-based networking, L7 policies, Hubble observability). The CNI cannot be changed after creation.

External etcd topology (kubeadm)

By default kubeadm runs etcd stacked on the control plane nodes. For larger clusters you can run etcd on dedicated instances by setting etcd_topology to external together with etcd_node_count and etcd_plan_id.

Node Groups

Node groups let you organize worker nodes into logical groups with independent service plans, counts, labels, and taints. Manage node groups from Settings > Nodes in the dashboard, or via the API.

Node Group API Reference

Endpoint	Method	Description
`/api/v1/clusters/morpheus/{id}/node-groups`	GET	List all node groups
`/api/v1/clusters/morpheus/{id}/node-groups`	POST	Add a node group
`/api/v1/clusters/morpheus/{id}/node-groups/{name}/scale`	PUT	Scale a node group (0-100)
`/api/v1/clusters/morpheus/{id}/node-groups/{name}/instance-type`	PUT	Change service plan
`/api/v1/clusters/morpheus/{id}/node-groups/{name}/labels`	PUT	Update labels
`/api/v1/clusters/morpheus/{id}/node-groups/{name}/taints`	PUT	Update taints
`/api/v1/clusters/morpheus/{id}/node-groups/{name}`	DELETE	Delete a node group

For detailed usage examples, see Hetzner Node Groups - the API is identical across all providers.

Legacy Worker Scaling

The legacy scale-workers and worker-count endpoints operate on all workers as a single pool.

curl https://platform.ankra.app/api/v1/clusters/morpheus/<cluster_id>/worker-count \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"

curl -X POST https://platform.ankra.app/api/v1/clusters/morpheus/<cluster_id>/scale-workers \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"worker_count": 4}'

Prefer using Node Groups for more granular control.

Upgrading Kubernetes Version

You can upgrade the Kubernetes version on all nodes in a Morpheus cluster. Upgrades are applied to control plane nodes first, then workers. Both k3s and kubeadm clusters are supported.

Both k3s and kubeadm clusters are supported for version upgrades, including kubeadm clusters with an external etcd topology: the dedicated etcd members are upgraded first, one at a time, each saving a pre-upgrade snapshot before its static pod rolls to the etcd image matching the target Kubernetes version.
Use the matching version format for the target: v1.35.1+k3s1 for k3s, or a plain v1.31.0 upstream tag for kubeadm.
Downgrades are not supported - downgrades require an etcd snapshot restore.
You can only upgrade one minor version at a time (e.g., v1.33.x to v1.34.x, not v1.33.x to v1.35.x).
The cluster must be online with no active operations.

Check Current Version

curl https://platform.ankra.app/api/v1/clusters/morpheus/<cluster_id>/k8s-version \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"

Upgrade Version

curl -X POST https://platform.ankra.app/api/v1/clusters/morpheus/<cluster_id>/upgrade-k8s-version \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_version": "v1.35.1+k3s1"}'

For a kubeadm cluster, use a plain upstream tag instead (for example "target_version": "v1.31.0").

Deprovisioning

Deprovisioning deletes all instances Ankra created through Morpheus (bastion, control planes, workers, and dedicated etcd instances if any) and removes the cluster from Ankra. Your Morpheus groups, clouds, networks, and virtual images are left untouched.

This action is irreversible. All data on the cluster will be permanently deleted.

curl -X DELETE https://platform.ankra.app/api/v1/clusters/morpheus/<cluster_id> \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"

Architecture

A Morpheus cluster provisions the following infrastructure:

Component	Description
Bastion Instance	Jump server for secure SSH access to cluster nodes
Control Plane(s)	Kubernetes control plane instances
Worker(s)	Kubernetes worker instances organized in node groups
etcd Node(s)	Dedicated etcd instances, only for kubeadm clusters with an `external` etcd topology
SSH Keys	Deployed to all instances for access

All instances are provisioned through your Morpheus appliance into the group, cloud, and network you selected, booting from the chosen virtual image with DHCP addressing. The bastion instance provides the only SSH access point Ankra uses to reach the cluster nodes. When an SSH jumphost is configured, Ankra reaches both the Morpheus API and the bastion through the jumphost.

Morpheus clusters do not include a cloud controller manager or load balancer integration - external_cloud_provider is not supported. Kubernetes LoadBalancer services are not provisioned automatically; expose workloads with NodePort services, an ingress controller, or a load balancer solution you deploy yourself.

Troubleshooting

Common Issues

Issue	Solution
Morpheus API unreachable from Ankra	Attach an SSH jumphost to the credential - Ankra tunnels API calls and node SSH through it
TLS certificate errors (self-signed)	Enable the TLS insecure toggle (`tls_insecure`) on the Morpheus credential
Instances never get an IP address	The selected network must provide DHCP - Ankra does not manage IP allocation. Verify a DHCP server answers on that network
Cluster stuck in provisioning	Check that the access token can provision into the selected group and cloud, and that the cloud has free capacity
Instance creation fails	Verify the virtual image is a Linux cloud image available to the selected cloud, and the service plan is valid for it
LoadBalancer service stuck in `Pending`	Morpheus clusters have no cloud controller manager - use `NodePort`, ingress, or your own load balancer
No cost estimates shown	Expected - cost estimation is not supported for Morpheus clusters

​Prerequisites

Morpheus API Credential

SSH Key Credential

​Hybrid Connectivity (SSH Jumphost)

​Creating a Morpheus Cluster

​Via the Platform UI

​Via the API

​Cluster Configuration Options

​Networking

​Kubernetes Distribution

​External etcd topology (kubeadm)

​Node Groups

​Node Group API Reference

​Legacy Worker Scaling

​Upgrading Kubernetes Version

​Check Current Version

​Upgrade Version

​Deprovisioning

​Architecture

​Troubleshooting

​Common Issues

Prerequisites

Hybrid Connectivity (SSH Jumphost)

Creating a Morpheus Cluster

Via the Platform UI

Via the API

Cluster Configuration Options

Networking

Kubernetes Distribution

External etcd topology (kubeadm)

Node Groups

Node Group API Reference

Legacy Worker Scaling

Upgrading Kubernetes Version

Check Current Version

Upgrade Version

Deprovisioning

Architecture

Troubleshooting

Common Issues