Managed Kubernetes

#What it is

A managed Kubernetes cluster is a set of virtual machines in your account that the platform sets up and joins into one cluster for you:

• Control nodes run the cluster's API and its state. A cluster has 1, or 3 for a highly available control plane where the zone offers it.
• Worker nodes run your workloads. A cluster has 1 to 10: a fixed number you change when you like, or a range the autoscaler moves within as your pods need.

Every node, control and worker, is a VM of the node plan you choose, and is billed as one. There is no separate fee for the control plane. You get an admin kubeconfig and use kubectl, Helm or anything else that speaks to Kubernetes, as with any other cluster.

#Zones and placement

A cluster lives in one zone, chosen when you create it, and cannot move.

A highly available control plane (3 control nodes) keeps the cluster's API up when one control node fails or is replaced. It is offered only in some zones: the create form shows it only where it can be created, and the API lists those zones as ha_zone_ids on the versions list. The number of control nodes is fixed once the cluster exists.

In a VPC zone, the subnet's network ACL applies to the nodes like any other VM in it.

#Create a cluster

1. In the console, choose Kubernetes in the sidebar, then press Create cluster.
2. Zone: where the cluster runs.
3. VPC and subnet (VPC zone only): the dedicated subnet the nodes go in. Each cluster requires its own dedicated subnet (/24 or /26 recommended) to prevent IP collisions with standard VMs or other clusters. Create a VPC and subnet first if you have none.
4. Version: the Kubernetes version, newest first. See versions and upgrades.
5. Node plan: the size of every node. It must have at least the version's minimum vCPU and memory.
6. Control plane: 1 control node, or 3 for high availability where the zone offers it.
7. Workers: a fixed number from 1 to 10, or turn on Autoscaling and set Minimum workers and Maximum workers. See autoscaling.
8. API server access (VPC zone only): Any address, or Only these addresses and list them. See API server access.
9. Name: 1 to 40 lowercase letters, digits and hyphens, starting with a letter, like prod-web. Press Generate if you want a random memorable name. It must be unique in your organization.

The summary shows how many nodes you are paying for (with autoscaling, as many as the maximum could run). Confirm. The cluster's page follows it from provisioning to running, which takes several minutes. Once it is running, download its kubeconfig.

A cluster must also fit your account's limits, with every node it could have counted (up to the autoscaling maximum). One that does not fit fails before anything is created: its operation ends failed with failure.code PROVISIONING_LIMIT_EXCEEDED, and no node is built or billed. Delete what you no longer use, ask for fewer workers or a lower maximum, or contact support to raise your limits.

#Versions and upgrades

Each zone offers a few Kubernetes versions. A version is withdrawn from new clusters before it reaches its upstream end of life; clusters already on it keep running it, but you should plan to upgrade.

• Upgrades are yours to start. A cluster is never upgraded on its own.
• One step at a time. A cluster can move to the next patch release, or to the next minor version (for example 1.31 to 1.32), never further in one go. To go from 1.30 to 1.32, upgrade twice.
• Never down. There is no downgrade. Test an upgrade on a separate cluster first if your workloads depend on APIs that change between versions.
• The cluster must be running. Nodes are replaced one at a time, so workloads running more than one replica, spread across workers, can keep serving.

On the cluster's page, the Upgrade button lists the versions the cluster can move to now. In the API they are the cluster's available_upgrades.

#Node plans and billing

Every node is a VM of the node plan, billed exactly as a VM of that plan: a cluster of 1 control node and 2 workers costs three VMs. The plan has to meet the version's minimum vCPU and memory; smaller plans are refused with INVALID_KUBERNETES_NODE_PLAN. The plan is chosen once; to change it, create a new cluster.

A public or dual cluster also pays for its own public address, as a static IP, for every hour it holds it; a private cluster has none. With autoscaling, you pay for the workers that are running, hour by hour, never for the maximum unless it runs. Storage your workloads claim through persistent volumes is billed as storage, with the nodes' disks. There is no control-plane fee. See how billing works.

#Scale the workers

On the cluster's page, press Change nodes, set Workers to any number from 1 to 10 and confirm. Added workers are billed from when they exist; removed workers are drained first, so their pods move to the others, and stop billing. The cluster must be running, and must not be in the middle of another change. Its state shows updating until the change is done: once every added worker has joined the cluster and is ready to run pods, about two minutes after it starts. Added workers take no upfront payment; they are checked against your funding (a saved card, or enough credit) and your account limits.

Setting the same number again changes nothing. While autoscaling is on you cannot set a fixed number: turn autoscaling off in the same dialog, and the cluster keeps the count you choose.

#Autoscaling

With autoscaling on, the platform's autoscaler checks the cluster about once a minute. It adds a worker when a pod that a worker could run is waiting for room, and removes the newest worker once it has run nothing but DaemonSet pods for 10 minutes. It moves one worker at a time, waits for a new worker to join before taking another step, and always stays between the minimum and the maximum you set. Node pools with autoscaling on are scaled the same way, for pods that select the pool and tolerate its taints.

• Turn it on when you create the cluster (Autoscaling in the create form), or later on the cluster's page under Change nodes. Set Minimum workers and Maximum workers.
• The range is 1 to 10, with the minimum no more than the maximum. A new cluster starts at the minimum. Changing the range on a running cluster moves the current count into it straight away.
• Billing: workers are billed as VMs of the node plan while they run, so you pay for what the autoscaler runs, hour by hour. Your funding (a saved card, or enough credit), and your account limits, are checked for the maximum when you turn autoscaling on or raise the maximum, so the autoscaler can always reach it. Nothing is paid up front.
• The worker count you see is what the autoscaler chose; it changes on its own. You cannot set a fixed count while autoscaling is on.
• Turn it off under Change nodes by choosing a fixed number of workers. The cluster keeps that many.

The autoscaler reacts to pods' resource requests, not to CPU use: give your pods resources.requests so it knows when the cluster is full.

#Node pools

A node pool is a group of workers beside the cluster's own, with its own plan, worker count (or autoscaling range), Kubernetes labels and taints: for example bigger nodes for a database, or nodes only some workloads may use. Every pool worker carries the label pantech.io/node-pool=<pool name>; give a workload a nodeSelector (and tolerations for the pool's taints) to run it there. Each worker is billed as a VM of the pool's plan once it has joined the cluster; the pool shows how many have (observed_workers). Deleting a pool removes its workers from the cluster (their pods move to nodes that can run them) and then destroys them.

In af-abj-2, every Kubernetes node is currently built at one fixed size, 2 vCPU and 4 GB, so clusters, plan changes and node pools there take plans of that size only (KUBERNETES_PLAN_NOT_IN_ZONE otherwise). You are billed for exactly the size you get.

#Add-ons

Turn them on or off on the cluster's Add-ons tab, with pantech kubernetes addons enable|disable, or the API. The platform keeps your choice applied, and each add-on's status (installing, active, removing, disabled) shows when it has taken effect.

#API server access

The API server is where kubectl and every other tool connect. Its URL is the cluster's endpoint, on the cluster's page under API server (endpoint in the API, null until the cluster is running), and the kubeconfig already points at it.

In a VPC zone, a cluster's endpoint access decides where the API server can be reached from (endpoint_access in the API):

Choose it when you create the cluster, or change it later with API server access on the cluster's page. A public or dual cluster gets a public address of its own: its API server is on port 6443 of it (public_ip and public_port in the API), and the services you expose are on it too. Switching a cluster to private releases that address: the change finishes only once the API server and every exposed service are no longer reachable from the internet, and the address stops being billed then. Every request still needs the kubeconfig's credential, whatever the endpoint access.

A public or dual cluster can also allow only the addresses you list:

1. On the cluster's page, press API server access (or choose it when you create the cluster).
2. Choose Only these addresses, and list up to 20 IPv4 ranges, such as your office's 203.0.113.0/24 or one machine's 198.51.100.7/32.
3. Save. The list you save replaces the old one; choose Any address to remove the limit again.

The list is enforced on the cluster's control node, against the address a connection really comes from. List the address your network uses on the internet: an office or home connection can go out from more than one, and only the ones listed get through. Traffic from inside your VPC and the cluster itself always gets through. The list only limits who reaches the API server: workloads inside the cluster, and services you expose, are not affected. Keep an address you will use to manage the cluster on the list, or you lock yourself out of kubectl until you change it again. Clusters created before 22 October 2026 cannot take a list; create a new cluster to use one. Clusters in a standard zone cannot have a list; asking for one is refused with API_ALLOWED_CIDRS_VPC_ONLY.

#Download the kubeconfig

The kubeconfig is the file kubectl reads to find and log in to your cluster. On the cluster's page, once it is running, press Download kubeconfig. Only owners and admins can download it.

Through the API it is POST /kubernetes-clusters/{cluster_id}/kubeconfig, which needs a write API key, so a read-only key can never fetch it. Before the cluster is running it answers 409 KUBECONFIG_UNAVAILABLE. With the CLI, pantech kubernetes kubeconfig prod -o ~/.kube/prod.yaml writes it to a file only you can read.

#Connect with kubectl

Install kubectl, ideally the same minor version as the cluster, and point it at the file:

$ chmod 600 ~/Downloads/prod-web-kubeconfig.yaml$ export KUBECONFIG=~/Downloads/prod-web-kubeconfig.yaml$ kubectl get nodesNAME              STATUS   ROLES           AGE   VERSIONprod-web-ctrl-1   Ready    control-plane   12m   v1.31.2prod-web-wrk-1    Ready    <none>          10m   v1.31.2prod-web-wrk-2    Ready    <none>          10m   v1.31.2

Node names in your cluster will differ. To use several clusters, merge their files or keep one KUBECONFIG per shell.

#Persistent volumes

Persistent volumes work out of the box: the cluster has a default storage class, so a PersistentVolumeClaim gets a volume without any setup.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 20Gi

The storage your claims use is the cluster's volume storage, on the cluster's page (volume_storage_gb in the API). It is billed as storage, with the nodes' disks, by the hour for as long as the volumes exist, whether the cluster is running or stopped. Delete claims you no longer need to stop paying for them. Deleting the cluster deletes them all, so copy out any data you need to keep first.

#Expose your services

In a VPC zone, route a public port of the cluster's address to a Service: Expose on the cluster's Workloads tab, pantech kubernetes expose <cluster> <service> --port 80, or POST …/expose-service. The service's port becomes a NodePort and the route is created on the cluster's own public address; the subnet's network ACL must let the port in. Only a public or dual cluster has a public address, so a private cluster cannot expose services, and switching a cluster to private takes its exposed services off the internet. The cluster is the record of what is exposed: an exposed service carries the pantechdynamics.com/public-port annotation, so removing it with kubectl and running Sync public routing (pantech kubernetes sync-routing) takes the route away.

A cluster has no cloud load-balancer integration: a Service of type LoadBalancer gets no address. A good pattern is to run an ingress controller as a NodePort service, expose that one port, and route every app through ingress rules. To spread traffic across several clusters or VMs, put a load balancer in front.

Services that only need to be reached from your VPC can stay private: in a VPC zone, other VMs in the VPC reach the nodes on their private addresses, subject to the subnet's network ACL.

#Stop and start

On the cluster's page, press Stop to stop every node. While stopped, only the nodes' disks are billed, and nothing in the cluster runs. Press Start to bring it back; its nodes are billed for compute again once it runs. You cannot scale or upgrade a stopped cluster, or download its kubeconfig.

#Delete a cluster

On the cluster's page, press Delete and confirm.

• At once, the cluster disappears from your lists and stops billing. Its name, its subnet and its place in your cluster limit are freed for reuse, and a public address it held is released.
• Within minutes, its nodes are stopped and destroyed with their disks, one node at a time. They cannot be recovered.
• Volumes your workloads created through persistent volume claims are deleted with it. Copy out any data you need first.

A subnet that still has clusters in it cannot be deleted: the API answers 409 SUBNET_HAS_KUBERNETES_CLUSTERS. Delete the clusters first.

#Limits

• 5 clusters per organization by default; a cluster you delete stops counting at once. Contact support to raise it.
• 1 to 10 workers per cluster, fixed or as an autoscaling range.
• Account limits: every node is a VM in your account and counts against its limits, up to the autoscaling maximum. A cluster or a scale that does not fit fails with PROVISIONING_LIMIT_EXCEEDED before anything is created.
• 20 addresses or ranges on the API server's allow-list, for a public or dual cluster in a VPC zone.
• 1 or 3 control nodes, 3 only where offered; fixed once created.
• Fixed once created: the name, the zone, the subnet, the node plan and the number of control nodes. To change any of them, create a new cluster.
• Changeable: the number of workers or the autoscaling range, the endpoint access and the API server's allow-list, and the version (upwards, one step at a time).

#Troubleshooting

A create or scale that is accepted can still fail: its operation then ends failed with a failure.code. PROVISIONING_LIMIT_EXCEEDED means the cluster, counting every node it could have, does not fit your account's limits; nothing was created. Ask for fewer workers or a lower maximum, delete what you no longer use, or contact support to raise the limits. See when an operation fails for the other codes.

On a 422 VALIDATION_FAILED, each entry of errors names the field and its code:

A cluster whose state is failed carries a failure_code and a readable failure_reason. The platform treats failed clusters as deleted, leaving them out of your cluster list so their name and subnet are immediately freed to create another cluster. If creation continues to fail, open a ticket with the operation's id.

#With the CLI

The CLI does every step from your terminal:

$ pantech kubernetes versions --zone af-abj-2$ pantech kubernetes create --name prod-web --zone af-abj-2 --version 1.31.2 \    --subnet snet_… --node-plan s-2vcpu-4gb --workers 2$ pantech kubernetes kubeconfig prod-web -o ~/.kube/prod-web.yaml$ pantech kubernetes configure prod-web --autoscale 2:5$ pantech kubernetes configure prod-web --api-allow 203.0.113.0/24$ pantech kubernetes upgrade prod-web --version 1.32.0$ pantech kubernetes apply prod-web -f app.yaml$ pantech kubernetes workloads prod-web$ pantech kubernetes expose prod-web web --port 80$ pantech kubernetes stop prod-web$ pantech kubernetes delete prod-web

kubeconfig refuses to print the credential unless you pass --stdout. configure --no-autoscale --workers 3 turns the autoscaler off at a fixed count, and --api-allow-any removes the allow-list.

#With the API

Every step is in the Kubernetes API. Using the pt and wait_op helpers from the API examples, with a subnet of a VPC in the VPC zone in $SUBNET:

source pantech.sh

# 1. Pick the newest version in the zone.
ZONE=af-abj-2
VERSION=$(pt GET "/kubernetes-versions?zone_id=$ZONE" | jq -r '[.data[] | select(.status == "available")][0].id')

# 2. Create the cluster: 1 control node, 2 workers.
OP=$(pt POST /kubernetes-clusters "$(jq -n --arg z "$ZONE" --arg v "$VERSION" --arg s "$SUBNET" \
  '{name: "prod-web", zone_id: $z, kubernetes_version_id: $v, subnet_id: $s,
    node_plan: "s-2vcpu-4gb", control_nodes: 1, workers: 2}')")
K8S=$(echo "$OP" | jq -r .resource_id); wait_op "$(echo "$OP" | jq -r .operation_id)"

# 3. Download the kubeconfig (a write key) and use it.
pt POST "/kubernetes-clusters/$K8S/kubeconfig" | jq -r .kubeconfig > kubeconfig.yaml
chmod 600 kubeconfig.yaml
KUBECONFIG=kubeconfig.yaml kubectl get nodes

Use a node plan from GET /plans that meets the version's min_cpu and min_memory_mb. To create it with the autoscaler instead, send autoscaling and leave workers out (it starts at min_workers); in a VPC zone you can limit the API server to your addresses at the same time:

OP=$(pt POST /kubernetes-clusters "$(jq -n --arg z "$ZONE" --arg v "$VERSION" --arg s "$SUBNET" \
  '{name: "prod-api", zone_id: $z, kubernetes_version_id: $v, subnet_id: $s, node_plan: "s-2vcpu-4gb",
    autoscaling: {enabled: true, min_workers: 2, max_workers: 5},
    api_allowed_cidrs: ["203.0.113.0/24"]}')")

PATCH /kubernetes-clusters/{cluster_id} changes the cluster: send any of workers, autoscaling and api_allowed_cidrs, and the rest stay as they are. An empty operation_id means nothing changed:

# A fixed number of workers (autoscaling must be off, or turned off in the same request).
OP=$(pt PATCH "/kubernetes-clusters/$K8S" '{"workers": 3}')
OPID=$(echo "$OP" | jq -r .operation_id)
[ -n "$OPID" ] && wait_op "$OPID"

# Let the autoscaler keep 2 to 5 workers.
pt PATCH "/kubernetes-clusters/$K8S" '{"autoscaling": {"enabled": true, "min_workers": 2, "max_workers": 5}}'

# Turn it off and keep 3 workers.
pt PATCH "/kubernetes-clusters/$K8S" '{"autoscaling": {"enabled": false, "min_workers": 0, "max_workers": 0}, "workers": 3}'

# Replace the API server's allow-list (VPC zone); [] allows any address again.
pt PATCH "/kubernetes-clusters/$K8S" '{"api_allowed_cidrs": ["203.0.113.0/24", "198.51.100.7/32"]}'

GET /kubernetes-clusters/{cluster_id} reports autoscaling, api_allowed_cidrs (empty for any address), endpoint (the API server's URL) and volume_storage_gb. Each PATCH returns an operation to follow, like the first one above.

To upgrade, pick one of the cluster's available_upgrades:

NEXT=$(pt GET "/kubernetes-clusters/$K8S" | jq -r '.available_upgrades[0].id')
OP=$(pt POST "/kubernetes-clusters/$K8S/upgrade" "$(jq -n --arg v "$NEXT" '{kubernetes_version_id: $v}')")
wait_op "$(echo "$OP" | jq -r .operation_id)"

POST /kubernetes-clusters/{cluster_id}/stop and /start stop and start it, and DELETE /kubernetes-clusters/{cluster_id} deletes it. Each returns an operation to follow.

#With Terraform

With the Terraform provider, a VPC, a subnet, a cluster of 1 control node whose workers the autoscaler keeps between 2 and 5, with its API server open only to your office, and its kubeconfig written to a file:

resource "pantechdynamics_network" "main" {
  name = "main"
  cidr = "10.0.0.0/16"
}

resource "pantechdynamics_subnet" "k8s" {
  network_id = pantechdynamics_network.main.id
  name       = "k8s"
  cidr       = "10.0.2.0/24"
}

# Let kubectl reach the cluster's API from your office.
resource "pantechdynamics_firewall_rule" "kube_api" {
  subnet_id  = pantechdynamics_subnet.k8s.id
  number     = 100
  protocol   = "tcp"
  port_start = 6443
  cidr       = "203.0.113.0/24"
}

data "pantechdynamics_kubernetes_versions" "zone" {
  zone_id = pantechdynamics_subnet.k8s.zone
}

resource "pantechdynamics_kubernetes_cluster" "prod" {
  name                  = "prod-web"
  zone_id               = pantechdynamics_subnet.k8s.zone
  subnet_id             = pantechdynamics_subnet.k8s.id
  kubernetes_version_id = data.pantechdynamics_kubernetes_versions.zone.versions[0].id # newest first
  node_plan             = "s-2vcpu-4gb"
  control_nodes         = 1 # or 3 where the zone is in ha_zone_ids

  # The autoscaler keeps 2 to 5 workers. Leave workers out while it is on.
  autoscaling = {
    enabled     = true
    min_workers = 2
    max_workers = 5
  }
  # For a fixed count instead: remove autoscaling and set workers = 2.

  # VPC zone only: who may reach the API server. Leave out for any address.
  api_allowed_cidrs = ["203.0.113.0/24"]

  timeouts = {
    create = "60m"
    update = "60m"
    delete = "20m"
  }
}

resource "local_sensitive_file" "kubeconfig" {
  filename        = "${path.module}/kubeconfig.yaml"
  content         = pantechdynamics_kubernetes_cluster.prod.kube_config
  file_permission = "0600"
}

output "kubernetes_version" {
  value = pantechdynamics_kubernetes_cluster.prod.kubernetes_version
}

output "endpoint" {
  value = pantechdynamics_kubernetes_cluster.prod.endpoint
}

• Set either workers (a fixed count, 1 to 10) or autoscaling with enabled = true, not both; the plan says so if you do. While autoscaling is on, workers reports the count the autoscaler chose and never shows as a change. To go back to a fixed count, remove autoscaling and set workers.
• Changing workers, autoscaling or api_allowed_cidrs changes the cluster in place, in one request. Removing api_allowed_cidrs allows any address again.
• Changing kubernetes_version_id upgrades it in place. Set it to one of the cluster's available_upgrade_ids; a downgrade is refused.
• Changing name, zone_id, subnet_id, node_plan or control_nodes replaces the cluster: Terraform deletes it and creates a new one, and everything in it is lost.
• kube_config is sensitive, and lands in your Terraform state. Keep the state somewhere private, encrypted at rest.
• observed_state, in_sync, nodes, node (its vcpu, memory_mb and disk_gb), network_id, endpoint and volume_storage_gb are read from the cluster.
• The pantechdynamics_kubernetes_cluster data source looks a cluster up by id or name, without its kubeconfig. It also reports autoscaling, api_allowed_cidrs, endpoint and volume_storage_gb.
• Import one with its id: terraform import pantechdynamics_kubernetes_cluster.prod k8s_06gk3x9tq7m2v8r4y1c5d0zp8w.