Access and networking - Namespace Documentation

Once an instance is running, client.compute also hands out the configuration needed to reach it: public ingresses, SSH and VNC endpoints, a kubeconfig, and the workspace network configuration. The examples on this page use a Compute client:

import { createComputeClient } from "@namespacelabs/sdk/api/compute";

const client = createComputeClient();

`compute.createIngress()`

Expose a backend inside the instance to the public internet, usually to serve HTTPS-terminated traffic from a container running in the instance. See Ingress for how Namespace routes and secures this traffic.

Example

const { allocatedIngresses } = await client.compute.createIngress({
  instanceId,
  ingresses: [
    {
      name: "api",
      exportedPortBackend: { port: 8080 },
    },
  ],
});

console.log(allocatedIngresses[0]?.fqdn);

API reference

createIngress(
  request: MessageInitShape<typeof CreateIngressRequestSchema>,
  options?: CallOptions,
): Promise<CreateIngressResponse>

Arguments and options

string

required

The instance that serves the backend.

IngressRequest[]

required

The ingresses to create.

Hide properties

string

required

The ingress name, matching [a-z0-9]([a-z0-9-_]*[a-z0-9])?.

ExportedPortBackend

The backend to route to, as a port and an optional ipAddress inside the instance.

HttpMatchRule[]

HTTP match rules for the ingress. Each rule carries a match and can set doesNotRequireAuth.

boolean

Routes all first-level subdomains of the instance wildcard domain to this ingress. Requires the instance to have a wildcard domain.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a CreateIngressResponse with allocatedIngresses. Each AllocatedIngress carries the name you requested, the allocated fqdn, and a description. If the instance does not exist, the call fails with NotFound.

`compute.listIngresses()`

List the backends exposed from an instance to the public internet. The response includes ingresses created with createIngress() and those exposed declaratively through the Kubernetes ingress manager feature.

Example

const { allocatedIngresses } = await client.compute.listIngresses({ instanceId });

for (const ingress of allocatedIngresses) {
  console.log(ingress.name, ingress.fqdn);
}

API reference

listIngresses(
  request: MessageInitShape<typeof ListIngressesRequestSchema>,
  options?: CallOptions,
): Promise<ListIngressesResponse>

Arguments and options

string

required

The instance to list ingresses for.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a ListIngressesResponse with allocatedIngresses. If the instance does not exist, the call fails with NotFound. If it is already terminated, the call fails with FailedPrecondition.

`compute.getSSHConfig()`

Return the configuration needed to open an SSH session to the instance. See SSH and remote display for what the session supports.

Example

const config = await client.compute.getSSHConfig({ instanceId });

console.log(`ssh ${config.username}@${config.endpoint}`);

API reference

getSSHConfig(
  request: MessageInitShape<typeof GetSSHConfigRequestSchema>,
  options?: CallOptions,
): Promise<GetSSHConfigResponse>

Arguments and options

string

required

The instance to provide an SSH configuration for.

string

A container name to connect to. The connection endpoint then targets that container.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetSSHConfigResponse.

string

The SSH endpoint to connect to. Use it together with username.

string

The username for the session, as in ssh <username>@<endpoint>.

Uint8Array

When set, a private key that establishes the session. Any key returned here has limited access rights, restricted to a single instance.

If the instance does not exist, the call fails with NotFound.

`compute.getVNCConfig()`

Return the configuration needed to reach the instance’s remote display over VNC.

Example

const config = await client.compute.getVNCConfig({ instanceId });

console.log(config.endpoint, config.username);

API reference

getVNCConfig(
  request: MessageInitShape<typeof GetVNCConfigRequestSchema>,
  options?: CallOptions,
): Promise<GetVNCConfigResponse>

Arguments and options

string

required

The instance to provide a VNC configuration for.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetVNCConfigResponse with the endpoint exposed by the instance ingress, and the username and password to use when the VNC server requires authentication. If the instance does not exist, the call fails with NotFound. If it exposes no VNC service, the call fails with FailedPrecondition.

The token used to connect to the returned endpoint must also grant access to the instance ingress.

`compute.getKubernetesConfig()`

Return a kubeconfig for the Kubernetes cluster running inside the instance.

Example

import { writeFile } from "node:fs/promises";

const { kubeconfig } = await client.compute.getKubernetesConfig({ instanceId });

await writeFile("kubeconfig.yaml", kubeconfig);

API reference

getKubernetesConfig(
  request: MessageInitShape<typeof GetKubernetesConfigRequestSchema>,
  options?: CallOptions,
): Promise<GetKubernetesConfigResponse>

Arguments and options

string

required

The instance to read the Kubernetes configuration from.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetKubernetesConfigResponse with kubeconfig, the configuration kubectl uses to reach Kubernetes inside the instance. If the instance does not exist, the call fails with NotFound. If it is not running Kubernetes, the call fails with FailedPrecondition.

`compute.getNetworkConfiguration()`

Return the network configuration of the workspace. Unlike the other methods on this page, it describes the workspace rather than one instance. See Networking for the wider picture.

Example

const { egress } = await client.compute.getNetworkConfiguration({});

for (const cidr of egress?.egressCidrs ?? []) {
  console.log(cidr.kind, cidr.cidr, cidr.segment);
}

API reference

getNetworkConfiguration(
  request: MessageInitShape<typeof GetNetworkConfigurationRequestSchema>,
  options?: CallOptions,
): Promise<GetNetworkConfigurationResponse>

Arguments and options

The request has no fields. Pass an empty object.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetNetworkConfigurationResponse whose egress carries egressCidrs. Each entry has a kind, the cidr itself, and the segment it belongs to. Use these ranges when you need to allow Namespace traffic through a firewall.

Create and manage instances

Create instances and start containers to expose.

Ingress

How Namespace routes and secures public traffic.

SSH and remote display

Interactive access to an instance.

​compute.createIngress()

​Example

​API reference

​Arguments and options

​Return value

​compute.listIngresses()

​Example

​API reference

​Arguments and options

​Return value

​compute.getSSHConfig()

​Example

​API reference

​Arguments and options

​Return value

​compute.getVNCConfig()

​Example

​API reference

​Arguments and options

​Return value

​compute.getKubernetesConfig()

​Example

​API reference

​Arguments and options

​Return value

​compute.getNetworkConfiguration()

​Example

​API reference

​Arguments and options

​Return value

​Related documentation

Create and manage instances

Ingress

SSH and remote display

`compute.createIngress()`

Example

API reference

Arguments and options

Return value

`compute.listIngresses()`

Example

API reference

Arguments and options

Return value

`compute.getSSHConfig()`

Example

API reference

Arguments and options

Return value

`compute.getVNCConfig()`

Example

API reference

Arguments and options

Return value

`compute.getKubernetesConfig()`

Example

API reference

Arguments and options

Return value

`compute.getNetworkConfiguration()`

Example

API reference

Arguments and options

Return value

Related documentation