Convert Kubernetes Manifests

The cpln convert command transforms Kubernetes manifests into Control Plane resources, enabling seamless migration from Kubernetes environments.

When to use this

Kubernetes migration

Migrate existing K8s workloads, secrets, and storage to Control Plane

Reuse existing manifests

Leverage your existing Kubernetes YAML files without rewriting them

Preview conversions

See how K8s resources translate to Control Plane before applying

CI/CD integration

Convert and apply K8s manifests in automated pipelines

Supported resources

Workload conversions

Kubernetes Kind	Control Plane Kind	Notes
Deployment	Workload	Type determined by spec analysis
ReplicaSet	Workload	Type determined by spec analysis
ReplicationController	Workload	Legacy K8s resource
StatefulSet	Workload	Type determined by spec analysis
DaemonSet	Workload	Type determined by spec analysis
Job	Workload (cron)	Converted to cron with default schedule
CronJob	Workload (cron)	Schedule preserved from spec

How workload type is determined

The converter analyzes your Kubernetes spec to automatically select the appropriate Control Plane workload type:

Cron

Job and CronJob resources always become cron workloads.

CronJobs preserve their schedule from spec.schedule
Jobs use a default schedule of * * * * * (every minute)

Stateful (highest priority)

The workload becomes stateful if any container mounts a volumeset (from PersistentVolumeClaim or volumeClaimTemplates).Stateful takes precedence over standard when both conditions are met.

Standard (default)

All non-cron workloads start as standard. The type remains standard unless a stateful condition is detected. Conditions that explicitly confirm standard:

A container has no ports or more than one port
A container uses gRPC health probes (liveness or readiness)
The workload has rollout options (from K8s strategy, updateStrategy, minReadySeconds, or podManagementPolicy)

Secret and config conversions

Kubernetes Kind	Control Plane Kind	Notes
Secret	Secret	Direct conversion
ConfigMap	Secret (dictionary)	Stored as dictionary secret

Storage conversions

Kubernetes Kind	Control Plane Kind	Notes
PersistentVolumeClaim	Volumeset	Persistent storage

Domain conversions

Kubernetes Kind	Control Plane Kind	Notes
Ingress	Domain	Routes converted from Ingress rules

How secrets are converted

Kubernetes Secrets are converted based on their type field:

K8s Secret Type	Control Plane Secret Type	Notes
`kubernetes.io/dockerconfigjson`	`docker`	Extracts `.dockerconfigjson` field
Any secret with a `payload` key	`opaque`	Checked before type-specific handling
`kubernetes.io/basic-auth`	`userpass`	Extracts `username` and `password` fields
`kubernetes.io/tls`	`dictionary`	Validated for `tls.crt` and `tls.key`, stored as key-value pairs
Default	`dictionary`	All other secrets become dictionaries

ConfigMaps are always converted to dictionary secrets, with all key-value pairs preserved. If a secret has both data and stringData fields, it is always converted to dictionary with both merged.

How volumesets are configured

PersistentVolumeClaims are converted to volumesets with these settings:

Property	Source (in priority order)	Default
Capacity	PersistentVolume `spec.capacity.storage` → PVC `spec.resources.requests.storage`	10 GB
Performance class	StorageClass parameters (see below)	`general-purpose-ssd`
File system type	PV volume source `fsType` → StorageClass `parameters.fsType`	`ext4`

High-performance SSD detection: If the StorageClass parameters contain any of these values, the volumeset uses high-throughput-ssd:

AWS: io1, io2
GCP: pd-extreme
Azure: UltraSSD_LRS
VMware: thick
Other: fast, persistent_1

How domains are converted

Kubernetes Ingresses are converted to Control Plane Domains. The converter maps Ingress rules (host + paths) to domain routes, resolving backend Services to workloads.

Field mapping

Kubernetes Ingress	Control Plane Domain	Notes
`metadata.labels`	`tags`	Labels preserved as domain tags
`spec.rules[].host`	`name`	Wildcard prefix (`*.`) stripped for domain name
`spec.rules[].host` (wildcard)	`spec.acceptAllSubdomains`	Set to `true` when host starts with `*.`
`spec.rules[].http.paths[].path`	Route `prefix` or `regex`	Depends on `pathType`
`spec.rules[].http.paths[].backend.service`	Route `workloadLink`	Resolved via Service selector → workload pod labels
Service `targetPort`	Route `port`	Container port resolved through the Service

Path type handling

Kubernetes `pathType`	Control Plane Route	Example
`Prefix`	`prefix: "/api"`	Default behavior
`Exact`	`regex: "^/api/v1/users$"`	Special characters escaped, anchored with `^` and `$`
`ImplementationSpecific`	`prefix: "/legacy"`	Treated as Prefix

Service-to-workload resolution

The converter resolves each Ingress backend to a Control Plane workload through the following steps:

Find the Service

The converter locates the Kubernetes Service referenced by the Ingress backend’s service.name.

Match the workload

The Service’s selector labels are matched against workload pod template labels to find the target workload.

Resolve the port

The Service port’s targetPort is resolved to the actual container port:

Numeric targetPort — used directly as the container port
Named targetPort — resolved by matching the port name in the container spec
No targetPort — falls back to the Service port number

Domain defaults

All converted domains use these fixed settings:

Property	Value
Port	`443`
Protocol	`http2`
DNS mode	`cname`
Certificate challenge	`http01`

Wildcard and apex domain merging

When an Ingress contains rules for both example.com and *.example.com, the converter merges them into a single domain named example.com with acceptAllSubdomains: true. Routes from both rules are combined and deduplicated.

Domains with acceptAllSubdomains enabled require a Dedicated Load Balancer on the target GVC.

GVC context

If a --gvc is provided, workload links use it directly (e.g., //gvc/my-gvc/workload/api). Otherwise, the converter inserts a {{GVC}} placeholder that you must replace before applying.

Auto-generated resources

When workloads reference secrets (via environment variables or volume mounts), the converter automatically creates:

Identity - Named identity-{workload-name}, linked to the workload
Policy - Named policy-{workload-name}, granting reveal permission on referenced secrets

This ensures workloads can access their secrets without manual policy configuration.

Firewall and public exposure

The converter analyzes your Kubernetes Services and Ingresses to determine if a workload should be publicly accessible:

Kubernetes Configuration	Control Plane Firewall
Service type `LoadBalancer` matching pod labels	External inbound allowed (`0.0.0.0/0`)
Ingress routing to a Service matching pod labels	External inbound allowed (`0.0.0.0/0`)
No public exposure detected	External inbound blocked (default)

All workloads have external outbound traffic allowed by default (0.0.0.0/0).

Informational resources

These Kubernetes resources are not directly converted but inform the conversion:

Resource	How it’s used
HorizontalPodAutoscaler	Sets `minScale`, `maxScale`, `scaleToZeroDelay`, and CPU target
Service	Protocol inference, public exposure detection, domain route resolution
ServiceAccount	Image pull secrets extraction
EndpointSlice	Service-to-Pod mapping for selectorless services
PersistentVolume	Capacity and file system type for volumesets
StorageClass	Performance class and file system type for volumesets

Basic usage

cpln convert --file <k8s-file>

This outputs the converted Control Plane resources to stdout.

Options

Option	Description
`--file`	Path to K8s JSON/YAML file. Use `--file -` for stdin
`--protocol`	Override port protocol for all containers: `http`, `http2`, `grpc`, `tcp`
`--verbose`	Show original K8s resources with ignored properties highlighted

How port protocol is inferred

When you don’t specify --protocol, the converter automatically infers the protocol for each container port using a multi-level strategy (in priority order):

Service appProtocol (highest priority)

If a Kubernetes Service explicitly declares appProtocol on a port that targets this container, that protocol is used.

spec:
  ports:
    - port: 50051
      targetPort: 50051
      appProtocol: grpc  # Explicitly declares gRPC

Service port name prefix

The converter checks if any Service port targeting this container has a name with a protocol prefix.

spec:
  ports:
    - name: grpc-api  # "grpc" prefix → gRPC protocol
      port: 50051

Container port name prefix

The container’s own port name is checked for protocol prefixes.

ports:
  - name: http-web  # "http" prefix → HTTP protocol
    containerPort: 8080

Health probe type

If the port has a liveness or readiness probe, the probe type determines the protocol:

grpc probe → gRPC
httpGet probe → HTTP
tcpSocket probe → TCP

Well-known port number (lowest priority)

Common port numbers are mapped to their typical protocols. See the tables below.

Recognized protocol prefixes

Port names starting with these prefixes are automatically mapped:

Prefix	Protocol
`http`, `https`, `ws`, `wss`	HTTP
`http2`, `h2`, `h2c`	HTTP/2
`grpc`, `grpc-web`, `grpcweb`	gRPC

Well-known port mappings

These port numbers are automatically assigned protocols when no other signal is available:

HTTP ports
gRPC ports

Port	Protocol
80, 81, 443	HTTP
3000, 3001, 3002	HTTP
8000, 8008, 8080, 8081, 8088	HTTP
8443, 9090	HTTP

Port	Protocol
50051, 50052, 50053, 50054, 50055	gRPC
6565	gRPC

If no protocol can be inferred, the converter defaults to tcp.

Example conversion

Create a Kubernetes manifest

Create a file named k8s.yaml:

k8s.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:latest
          ports:
            - containerPort: 80

Convert the manifest

cpln convert --file k8s.yaml

View output

kind: workload
name: example-deployment
spec:
  type: standard
  containers:
    - name: nginx
      image: 'nginx:latest'
      ports:
        - number: 80
          protocol: http
  defaultOptions:
    capacityAI: false
    autoscaling:
      minScale: 3
      maxScale: 3

Apply the converted resources

Convert and apply in one command:

cpln apply --file k8s.yaml --k8s true

Or pipe the conversion output:

cpln convert --file k8s.yaml | cpln apply --file -

More conversion examples

A simple Deployment with one HTTP port becomes standard (the default type):

k8s-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  template:
    spec:
      containers:
        - name: api
          image: my-api:v1
          ports:
            - containerPort: 8080

Converts to a standard workload (the default type for all non-cron, non-stateful workloads).

A Deployment with multiple ports or gRPC probes also becomes standard:

k8s-multiport.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: grpc-service
spec:
  replicas: 2
  selector:
    matchLabels:
      app: grpc-service
  template:
    spec:
      containers:
        - name: grpc-service
          image: my-grpc:v1
          ports:
            - containerPort: 50051
          readinessProbe:
            grpc:
              port: 50051

Converts to a standard workload (gRPC probe triggers standard type).

A StatefulSet with persistent storage becomes stateful:

k8s-statefulset.yaml

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
spec:
  serviceName: postgres
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    spec:
      containers:
        - name: postgres
          image: postgres:15
          ports:
            - containerPort: 5432
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

Converts to a stateful workload with a volumeset (storage triggers stateful type).

CronJobs preserve their schedule:

k8s-cronjob.yaml

apiVersion: batch/v1
kind: CronJob
metadata:
  name: daily-backup
spec:
  schedule: "0 2 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: backup
              image: backup-tool:latest
              command: ["/bin/sh", "-c", "backup.sh"]
          restartPolicy: OnFailure

Converts to a cron workload with schedule 0 2 * * *.

ConfigMaps become dictionary secrets:

k8s-configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  DATABASE_URL: "postgres://localhost:5432/mydb"
  LOG_LEVEL: "info"

Converts to a dictionary secret containing the key-value pairs.

An Ingress with a Deployment and Service becomes a domain with routes:

k8s-ingress.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: my-api:v1
          ports:
            - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: api-service
spec:
  selector:
    app: api
  ports:
    - port: 80
      targetPort: 8080
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  labels:
    team: backend
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 80

Converts to a workload and a domain with routes pointing to the workload:

View output

kind: workload
name: api-server
spec:
  type: standard
  containers:
    - name: api
      image: 'my-api:v1'
      ports:
        - number: 8080
          protocol: http
  defaultOptions:
    capacityAI: false
    autoscaling:
      minScale: 2
      maxScale: 2
  firewallConfig:
    external:
      inboundAllowCIDR:
        - 0.0.0.0/0
      outboundAllowCIDR:
        - 0.0.0.0/0
---
kind: domain
name: api.example.com
description: 'Converted from K8s Ingress: api-ingress'
tags:
  team: backend
spec:
  dnsMode: cname
  certChallengeType: http01
  ports:
    - number: 443
      protocol: http2
      routes:
        - prefix: /api
          workloadLink: '//gvc/{{GVC}}/workload/api-server'
          port: 8080

Provide --gvc to replace the {{GVC}} placeholder with an actual GVC name in workload links.

Override protocol inference

To bypass automatic protocol inference and set a specific protocol for all ports, use the --protocol flag:

# Force all ports to use gRPC
cpln convert --file k8s.yaml --protocol grpc

# Force all ports to use TCP
cpln convert --file k8s.yaml --protocol tcp

Verbose mode

Use --verbose to see which K8s properties were converted and which were ignored:

cpln convert --file k8s.yaml --verbose

Ignored properties are highlighted in yellow and marked with (ignored).

Delete converted resources

To remove resources that were applied from a K8s manifest:

cpln delete --file k8s.yaml --k8s true

Troubleshooting

Resource type not supported

Some Kubernetes resources don’t have direct Control Plane equivalents. Use --verbose to see which properties are ignored during conversion.

ConfigMap values not appearing

ConfigMaps are converted to dictionary secrets. Reference them in your workload using environment variables or volume mounts pointing to the secret.

HPA settings not applied

HorizontalPodAutoscaler settings inform the workload’s autoscaling configuration. Check the converted workload’s defaultOptions.autoscaling section.

Service ports not exposed

Services are used to inform port mappings but don’t create standalone resources. Ports are configured directly on the workload’s container spec.

PVC not creating volumeset

PersistentVolumeClaims are converted to volumesets. Ensure the PVC is referenced by a StatefulSet’s volumeClaimTemplates for proper conversion.

Ingress not creating a domain

Ingress conversion requires the referenced Services and their matching workloads (Deployments, StatefulSets, etc.) to be present in the same file. The converter uses the Service selector to find the target workload by matching pod template labels.

Service without selector error

Ingress backend Services must have a selector defined so the converter can resolve which workload the Service targets. Services without selectors (e.g., ExternalName services) are not supported for domain conversion.

Workload link shows {{GVC}} placeholder

When converting Ingresses without specifying --gvc, workload links contain a {{GVC}} placeholder. Provide --gvc during conversion or replace the placeholder before applying.

Next steps

Apply YAML Manifests

Learn more about applying resources

Delete Resources

Remove resources from Control Plane

Workload Reference

Understand workload configuration

Convert Command Reference

Convert command reference

​When to use this

Kubernetes migration

Reuse existing manifests

Preview conversions

CI/CD integration

​Supported resources

​Workload conversions

​How workload type is determined

​Secret and config conversions

​Storage conversions

​Domain conversions

​How secrets are converted

​How volumesets are configured

​How domains are converted

​Field mapping

​Path type handling

​Service-to-workload resolution

​Domain defaults

​Wildcard and apex domain merging

​GVC context

​Auto-generated resources

​Firewall and public exposure

​Informational resources

​Basic usage

​Options

​How port protocol is inferred

​Recognized protocol prefixes

​Well-known port mappings

​Example conversion

​More conversion examples

​Override protocol inference

​Verbose mode

​Delete converted resources

​Troubleshooting

​Next steps

Apply YAML Manifests

Delete Resources

Workload Reference

Convert Command Reference

When to use this

Supported resources

Workload conversions

How workload type is determined

Secret and config conversions

Storage conversions

Domain conversions

How secrets are converted

How volumesets are configured

How domains are converted

Field mapping

Path type handling

Service-to-workload resolution

Domain defaults

Wildcard and apex domain merging

GVC context

Auto-generated resources

Firewall and public exposure

Informational resources

Basic usage

Options

How port protocol is inferred

Recognized protocol prefixes

Well-known port mappings

Example conversion

More conversion examples

Override protocol inference

Verbose mode

Delete converted resources

Troubleshooting

Next steps