Managed Kubernetes

Our Managed Kubernetes gives each workspace a managed k3s cluster. Activating it provisions control-plane infrastructure for the workspace. You then enroll instances as worker nodes, deploy containerized services, and store secrets that those services can reference. All provisioning and teardown operations are asynchronous.

Cluster

Get cluster status

GET/v1/workspaces/{wid}/k3sGet managed Kubernetes status

Returns the cluster record for the workspace, including its lifecycle status.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID

Returns a cluster object with the fields below.

Field	Type	Description
`id`	string	Cluster ID
`owner`	object	Workspace summary
`name`	string	Cluster namespace identifier
`status`	string	Lifecycle status: `PROVISIONING`, `ACTIVE`, `DEPROVISIONING`, or `FAILED`

Activate managed Kubernetes

POST/v1/workspaces/{wid}/k3sActivate managed Kubernetes

Provisions a managed k3s cluster for the workspace. This is asynchronous; poll the returned workflow or re-fetch GET /v1/workspaces/{wid}/k3s and wait for status to become ACTIVE.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID

No request body.

bash

curl -X POST https://api.galaxygate.net/v1/workspaces/42/k3s \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN"

Returns a workflow. Poll GET /v1/workspaces/{wid}/k3s until status is ACTIVE.

Deactivate managed Kubernetes

DELETE/v1/workspaces/{wid}/k3sDeactivate managed Kubernetes

Removes all nodes, services, and secrets, then tears down the cluster. This is destructive and asynchronous.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID

Returns a workflow.

Worker nodes

List worker nodes

GET/v1/workspaces/{wid}/k3s/nodesList worker nodes

Lists all worker nodes enrolled in the cluster, with pagination. Each entry includes live status from the cluster when available.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID

Query parameters

Name	Type	Description
`id`	integer[]	Filter to specific node IDs
`status`	string	Filter by node status (`JOINING`, `READY`, `DRAINING`, `FAILED`)
`instance`	integer[]	Filter by instance IDs

Plus the shared pagination parameters. Returns a paged list of node objects.

Add a worker node

POST/v1/workspaces/{wid}/k3s/nodesAdd a worker node

Enrolls an instance as a worker node. The instance must be running and belong to the same workspace. This is asynchronous.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID

Request body

Field	Type	Required	Description
`instance_id`	integer	yes	Instance ID to enroll as a worker node

bash

curl -X POST https://api.galaxygate.net/v1/workspaces/42/k3s/nodes \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "instance_id": 101 }'

Returns a workflow. Poll GET /v1/workspaces/{wid}/k3s/nodes/{id} until node.status is READY.

Get a worker node

GET/v1/workspaces/{wid}/k3s/nodes/{id}Get node details

Returns one node record plus live status from the cluster.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID
`id`	integer	Node ID

Returns an object with a node field and a live field (null when the control plane is unreachable).

Field	Type	Description
`node.id`	string	Node ID
`node.workspace`	object	Workspace summary
`node.instance`	object	Instance summary
`node.node_name`	string	Node name inside the cluster
`node.status`	string	`JOINING`, `READY`, `DRAINING`, or `FAILED`
`live.ready`	boolean	Whether the node is ready in the cluster
`live.conditions`	object	Node condition map, for example `{ "MemoryPressure": "False" }`
`live.allocatable`	object	Allocatable resource map, for example `{ "cpu": "4", "memory": "8Gi", "pods": "110" }`

Remove a worker node

DELETE/v1/workspaces/{wid}/k3s/nodes/{id}Remove a worker node

Drains the node and removes it from the cluster. Running pods are rescheduled if resources allow. This is asynchronous.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID
`id`	integer	Node ID

Returns a workflow.

Look up the node for an instance

GET/v1/instances/{iid}/k3sLook up node by instance

Returns the worker node record associated with a specific instance. Useful when you know the instance ID but not the node ID.

Path parameters

Name	Type	Description
`iid`	integer	Instance ID

Returns the same node object (with live status) as Get a worker node.

Services

List services

GET/v1/workspaces/{wid}/k3s/servicesList services

Lists all deployed services in the cluster, with pagination. Each entry includes live status when available.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID

Query parameters

Name	Type	Description
`q`	string	Quick search by name or ID
`id`	integer[]	Filter to specific service IDs
`name`	string	Filter by name (partial match)
`mode`	string	Filter by deployment mode (`PINNED` or `SPREAD`)
`status`	string	Filter by service status

Plus the shared pagination parameters. Returns a paged list of service objects.

Create a service

POST/v1/workspaces/{wid}/k3s/servicesCreate a service

Deploys a new containerized service onto the cluster. This is asynchronous.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID

Request body

Field	Type	Required	Description
`name`	string	yes	Service name, unique within the workspace
`image`	string	yes	Docker image URL including tag, for example `nginx:1.27`
`mode`	string	yes	`PINNED` schedules pods only on `target_instances`; `SPREAD` schedules across all nodes up to `replicas`
`target_instances`	integer[]	yes	Instance IDs the scheduler is allowed to use
`replicas`	integer		Number of replicas; only meaningful for `SPREAD` mode (default `1`)
`ports`	object[]		Port mappings; each entry has `host_port`, `container_port`, `protocol` (`TCP` or `UDP`), and `http` (boolean marking ports eligible for a custom subdomain)
`volumes`	object[]		Volume mounts; each entry has `host_path` and `container_path`
`environment`	object		Environment variables as a flat key-value map
`secret_refs`	string[]		Names of secrets whose key-value pairs are injected as environment variables
`update_strategy`	string		`ROLLING` (default) or `START_FIRST`

bash

curl -X POST https://api.galaxygate.net/v1/workspaces/42/k3s/services \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web",
    "image": "nginx:1.27",
    "mode": "SPREAD",
    "target_instances": [101, 102],
    "replicas": 2,
    "ports": [
      { "host_port": 8080, "container_port": 80, "protocol": "TCP", "http": true }
    ],
    "update_strategy": "ROLLING"
  }'

Returns a workflow. Poll GET /v1/workspaces/{wid}/k3s/services/{id} until service.status is RUNNING.

Get a service

GET/v1/workspaces/{wid}/k3s/services/{id}Get service details

Returns the full service configuration and live replica status.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID
`id`	integer	Service ID

Returns an object with a service field (full configuration) and a live field (null when unavailable).

Field	Type	Description
`service.id`	string	Service ID
`service.name`	string	Service name
`service.image`	string	Docker image URL including tag
`service.mode`	string	`PINNED` or `SPREAD`
`service.target_instances`	object[]	Target instance summaries
`service.replicas`	integer	Replica count
`service.ports`	object[]	Port mappings
`service.volumes`	object[]	Volume mounts
`service.secret_refs`	string[]	Referenced secret names
`service.update_strategy`	string	`ROLLING` or `START_FIRST`
`service.status`	string	`DEPLOYING`, `RUNNING`, `UPDATING`, `DELETING`, `FAILED`, or `STOPPED`
`live.desired_replicas`	integer	How many replicas are requested
`live.available_replicas`	integer	Replicas that are ready
`live.unavailable_replicas`	integer	Replicas that are not ready
`live.updated_replicas`	integer	Replicas on the current revision
`live.updating`	boolean	Whether a rollout is in progress
`live.pods`	object[]	Per-pod status: `name`, `phase`, `restart_count`, `ready`, `node_name`

Update a service

PUT/v1/workspaces/{wid}/k3s/services/{id}Update a service

Replaces the service configuration and triggers a redeployment. All fields except name and mode can be changed. Send the full desired state; omitted optional fields are cleared.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID
`id`	integer	Service ID

Request body

Field	Type	Required	Description
`image`	string	yes	Docker image URL including tag
`target_instances`	integer[]	yes	Instance IDs the scheduler is allowed to use
`replicas`	integer		Replica count (SPREAD mode only)
`ports`	object[]		Port mappings
`volumes`	object[]		Volume mounts
`environment`	object		Environment variables as a flat key-value map
`secret_refs`	string[]		Secret names to inject
`update_strategy`	string		`ROLLING` or `START_FIRST`

Returns a workflow.

Delete a service

DELETE/v1/workspaces/{wid}/k3s/services/{id}Delete a service

Removes the service from the cluster and deletes its record. This is asynchronous.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID
`id`	integer	Service ID

Returns a workflow.

Get service logs

GET/v1/workspaces/{wid}/k3s/services/{id}/logsGet service logs

Fetches container logs. Returns plain text. To stream logs in real time, add ?follow to the URL; the server responds with text/event-stream (SSE) instead.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID
`id`	integer	Service ID

Query parameters

Name	Type	Description
`tail`	integer	Number of lines to return from the end of the log (default 100)
`since_seconds`	integer	Return only log lines newer than this Unix timestamp in seconds
`pod_index`	integer	For `SPREAD` services with multiple replicas, select which pod by zero-based index (default 0)
`follow`	(flag)	When present, switches the response to an SSE stream (`text/event-stream`)

Returns text/plain log content, or an SSE stream when follow is present.

Redeploy a service

POST/v1/workspaces/{wid}/k3s/services/{id}/redeployRedeploy a service

Force-restarts the service using its current configuration. Useful for picking up an updated image at the same tag.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID
`id`	integer	Service ID

No request body. Returns a workflow.

Rollback a service

POST/v1/workspaces/{wid}/k3s/services/{id}/rollbackRollback a service

Reverts the service to the previous revision.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID
`id`	integer	Service ID

No request body. Returns a workflow.

Secrets

Secrets store sensitive key-value pairs. The API never returns secret values; only the name and key names are included in responses. Once a secret is referenced by a service (secret_refs), deleting it is blocked until the reference is removed.

List secrets

GET/v1/workspaces/{wid}/k3s/secretsList secrets

Lists all secrets in the workspace, returning names and key names only. Values are never returned.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID

Plus the shared pagination parameters. Returns a paged list of secret objects.

Field	Type	Description
`id`	string	Secret ID
`name`	string	Secret name
`keys`	string[]	Key names stored in this secret (values omitted)

Create a secret

POST/v1/workspaces/{wid}/k3s/secretsCreate a secret

Creates a secret with one or more key-value pairs. Each pair is injected as an environment variable into services that list this secret in secret_refs.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID

Request body

Field	Type	Required	Description
`name`	string	yes	Secret name, unique within the workspace
`data`	object	yes	Key-value pairs to store, for example `{ "DB_PASSWORD": "s3cr3t" }`

bash

curl -X POST https://api.galaxygate.net/v1/workspaces/42/k3s/secrets \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "db-credentials",
    "data": {
      "DB_USER": "app",
      "DB_PASSWORD": "s3cr3t"
    }
  }'

Returns the secret object (name and keys only; values are not echoed back).

Update a secret

PUT/v1/workspaces/{wid}/k3s/secrets/{id}Update a secret

Replaces all key-value pairs in the secret. This is a full replacement: any keys not present in data are removed.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID
`id`	integer	Secret ID

Request body

Field	Type	Required	Description
`data`	object	yes	New key-value pairs; replaces all existing pairs

Returns the updated secret object (name and keys only).

Delete a secret

DELETE/v1/workspaces/{wid}/k3s/secrets/{id}Delete a secret

Deletes the secret. Returns 409 Conflict if any service still references this secret in its secret_refs.

Path parameters

Name	Type	Description
`wid`	integer	Workspace ID
`id`	integer	Secret ID

Returns 204 No Content.

Managed Kubernetes ​

Cluster ​

Get cluster status ​

Activate managed Kubernetes ​

Deactivate managed Kubernetes ​

Worker nodes ​

List worker nodes ​

Add a worker node ​

Get a worker node ​

Remove a worker node ​

Look up the node for an instance ​

Services ​

List services ​

Create a service ​

Get a service ​

Update a service ​

Delete a service ​

Get service logs ​

Redeploy a service ​

Rollback a service ​

Secrets ​

List secrets ​

Create a secret ​

Update a secret ​

Delete a secret ​

Managed Kubernetes

Cluster

Get cluster status

Activate managed Kubernetes

Deactivate managed Kubernetes

Worker nodes

List worker nodes

Add a worker node

Get a worker node

Remove a worker node

Look up the node for an instance

Services

List services

Create a service

Get a service

Update a service

Delete a service

Get service logs

Redeploy a service

Rollback a service

Secrets

List secrets

Create a secret

Update a secret

Delete a secret