Run a Command in an Instance

CommandService runs a command inside a container and returns its output, with no ingress, SSH key, or port to configure. Reaching it takes two clients: the Compute API creates the instance, and the response carries a per-instance regional endpoint that serves the command service.

Create an instance that stays alive

The container has to be running when the command arrives, so give it a process that waits. sleep is enough.

import { loadDefaults } from "@namespacelabs/sdk/auth";
import { createComputeClient } from "@namespacelabs/sdk/api/compute";
import { timestampFromDate } from "@bufbuild/protobuf/wkt";

const tokenSource = await loadDefaults();
const computeClient = createComputeClient({ tokenSource });

const created = await computeClient.compute.createInstance({
  shape: { virtualCpu: 2, memoryMegabytes: 4096, machineArch: "amd64" },
  documentedPurpose: "exec example",
  deadline: timestampFromDate(new Date(Date.now() + 10 * 60 * 1000)),
  containers: [
    {
      name: "ubuntu",
      imageRef: "ubuntu:latest",
      args: ["sleep", "600"],
    },
  ],
});

const instanceId = created.metadata!.instanceId;

token, err := auth.LoadDefaults()
if err != nil {
	return err
}

computeClient, err := compute.NewClient(ctx, token)
if err != nil {
	return err
}
defer computeClient.Close()

resp, err := computeClient.Compute.CreateInstance(ctx, &computepb.CreateInstanceRequest{
	Shape: &computepb.InstanceShape{
		VirtualCpu:      2,
		MemoryMegabytes: 4 * 1024,
		MachineArch:     "amd64",
	},
	DocumentedPurpose: "exec example",
	Deadline:          timestamppb.New(time.Now().Add(10 * time.Minute)),
	Containers: []*computepb.ContainerRequest{{
		Name:       "ubuntu",
		ImageRef:   "ubuntu:latest",
		Entrypoint: []string{"sleep", "600"},
		Args:       []string{},
	}},
})
if err != nil {
	return fmt.Errorf("failed to create instance: %w", err)
}

Read the command service endpoint

The create response carries the endpoint in extendedMetadata.commandServiceEndpoint. It is a regional base URL, such as https://zrh2.compute.namespaceapis.com, and the region depends on where the instance landed rather than on where you called the API from. Read it from the response instead of hardcoding it.

const endpoint = created.extendedMetadata?.commandServiceEndpoint;
if (!endpoint) {
  throw new Error("command service endpoint not available");
}

endpoint := resp.ExtendedMetadata.GetCommandServiceEndpoint()
if endpoint == "" {
	return fmt.Errorf("command service endpoint not available")
}

There is no need to call WaitInstanceSync first. The command service accepts the call as soon as the container is up, so going straight from CreateInstance to RunCommandSync is the fastest path from nothing to running code.

Open a client against that endpoint

The endpoint is a separate service from the Compute API, so it needs its own client carrying the same credential.

import { createClient } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-node";
import { bearerAuthInterceptor } from "@namespacelabs/sdk/api";
import { CommandService } from "@namespacelabs/sdk/proto/namespace/cloud/compute/v1beta/command_pb";

const cmdTransport = createConnectTransport({
  httpVersion: "1.1",
  baseUrl: endpoint,
  useBinaryFormat: false,
  interceptors: [bearerAuthInterceptor(tokenSource)],
});

const cmdClient = createClient(CommandService, cmdTransport);

import "namespacelabs.dev/integrations/nsc/grpcapi"

conn, err := grpcapi.NewConnectionWithEndpoint(ctx, endpoint, token)
if err != nil {
	return fmt.Errorf("failed to connect to command service: %w", err)
}
defer conn.Close()

cmdCli := computepb.NewCommandServiceClient(conn)

Run the command

targetContainerName selects which container in the instance runs the command. RunCommandSync blocks and returns the full output, while RunCommand streams it.

const result = await cmdClient.runCommandSync({
  instanceId,
  targetContainerName: "ubuntu",
  command: { command: ["uname", "-a"] },
});

const decoder = new TextDecoder();
process.stdout.write(decoder.decode(result.stdout));

if (result.exitCode !== 0) {
  throw new Error(`command exited with code ${result.exitCode}`);
}

result, err := cmdCli.RunCommandSync(ctx, &computepb.RunCommandRequest{
	InstanceId:          resp.Metadata.InstanceId,
	TargetContainerName: "ubuntu",
	Command: &computepb.Command{
		Command: []string{"uname", "-a"},
	},
})
if err != nil {
	return fmt.Errorf("failed to run command: %w", err)
}

fmt.Fprintf(os.Stdout, "%s", result.Stdout)

if result.ExitCode != 0 {
	return fmt.Errorf("command exited with code %d", result.ExitCode)
}

stdout and stderr are returned as bytes.

Source

go/exec and typescript/exec in github.com/namespacelabs/examples.

Build with Namespace

Building Blocks

Create an instance that stays alive

Read the command service endpoint

Open a client against that endpoint

Run the command

Source

Create an instance that stays alive

Read the command service endpoint

Open a client against that endpoint

Run the command

​Source

Source