Package namespace.cloud.compute.v1beta

Class ComputeServiceGrpc.ComputeServiceFutureStub

java.lang.Object
io.grpc.stub.AbstractStub<ComputeServiceGrpc.ComputeServiceFutureStub>
io.grpc.stub.AbstractFutureStub<ComputeServiceGrpc.ComputeServiceFutureStub>
namespace.cloud.compute.v1beta.ComputeServiceGrpc.ComputeServiceFutureStub
Enclosing class:
ComputeServiceGrpc
public static final class ComputeServiceGrpc.ComputeServiceFutureStub extends io.grpc.stub.AbstractFutureStub<ComputeServiceGrpc.ComputeServiceFutureStub>
A stub to allow clients to do ListenableFuture-style rpc calls to service ComputeService. 
 ComputeService allows the creation, and management of compute instances.
 Compute instances are micro-vm backed environments which boot very quickly
 and are optimized to run containers.
 See https://namespace.so/docs/architecture/compute for an overview.
 ## Access
 ComputeService is segregated into isolated regions for fault tolerance.
 Each of the regional API endpoints offers a view into the compute instances
 running at that location. Reach out to Namespace team at support@namespace.so
 for a list of available regions.
 ```
 https://{region}.compute.namespaceapis.com:443
 # E.g.:
 https://eu.compute.namespaceapis.com:443
 https://us.compute.namespaceapis.com:443
 ```
 See [the overview](https://buf.build/namespace/cloud) for examples accessing
 the API from the console.
 ## SDKs and Examples
 **Go SDK**: [namespacelabs.dev/integrations](https://github.com/namespacelabs/integrations) —
 provides ready-to-use gRPC clients and authentication helpers.
 **TypeScript SDK**: [@namespacelabs/sdk](https://github.com/namespacelabs/typescript-sdk) —
 provides typed clients, authentication, and token management for Node.js.
 **Examples** (Go, TypeScript, Python):
 [createinstance](https://github.com/namespacelabs/examples/tree/master/go/createinstance),
 [kubernetes-demo](https://github.com/namespacelabs/examples/tree/master/typescript/kubernetes-demo),
 [containers-demo](https://github.com/namespacelabs/examples/tree/master/typescript/containers-demo),
 [ingress](https://github.com/namespacelabs/examples/tree/master/go/ingress),
 and [more](https://github.com/namespacelabs/examples).
 ## Authentication
 Calls to the ComputeService require a *tenant token* or a *workload token*
 passed as a Bearer token as part of each call. These are always required.
 A *tenant token* identifies both the workspace that the call operates on, but
 may also constrain the set of actions that the caller may do.
 A *workload token* identifies a running instance, and the workspace it is
 running in. Each running instance has a workload token, which is
 automatically made available to services running inside the instance.
 A *tenant token* can be obtained using the
 [IAM API](https://buf.build/namespace/cloud/docs/main:namespace.cloud.iam.v1beta).
 ## Guest services
 Managed guest services such as docker that are deployed and managed by
 Namespace are reachable using the corresponding standard APIs, through the
 public internet.
 Because these services typically don't support Namespace-based encapsulation,
 a client-side proxy is used to transport the application-specific protocol
 over the Namespace's public ingress, into the instance.
 To facilitate communication, the main underlying mechanism to transport the
 application-specific protocol is WebSockets over HTTPS.
 ### Example: using the Docker API
 To call the Docker API remotely, first obtain the Docker public endpoint by
 querying the set of running Services, using the DescribeInstance call.
 Iterate over `metadata.services` until finding an entry with `name=docker`.
 Establish an HTTPS connection to the contained `endpoint`, and upgrade it to
 a WebSocket. To authenticate your request include an authentication token
 (see Authentication) in the `x-nsc-ingress-auth` header.
 If connecting using a browser, where setting headers is not possible, you can
 instead construct a URL using the base endpoint, and passing
 `x-nsc-ingress-auth` as a query string argument.
 After the WebSocket is established, any frames received or sent of type
 BinaryMessage carry application-specific payload.

  • Method Details

    • build

      protected ComputeServiceGrpc.ComputeServiceFutureStub build(io.grpc.Channel channel, io.grpc.CallOptions callOptions)
      Specified by:
      build in class io.grpc.stub.AbstractStub<ComputeServiceGrpc.ComputeServiceFutureStub>

    • createInstance

      public com.google.common.util.concurrent.ListenableFuture<Compute.DescribeInstanceResponse> createInstance(Compute.CreateInstanceRequest request)
       Creates a new instance. Instances are micro-vm backed environments which
 are optimized to run containers. Each instance is deployed with
 `containerd`, and with optionally `dockerd` and Kubernetes.
 Instances can run one or more containers. Containers can be started using
 one of two mechanisms:
 - Namespace managed containers: containers are specified at creation time
   via the `containers` field, or at runtime via the `StartContainers`
   method. Managed containers have logs and metrics automatically
   collected, and Namespace's infrastructure optimizes future startup time
   of repeated use of the same containers. These containers are handled as
   "critical" and their lifetime is tied to the VMs -- if they fail,
   either due to early exit, OOM, etc, the instance also fails. Namespace
   managed containers are always run on containerd directly, in the
   `default` namespace.
 - User-managed containers: after an instance is created, you can use the
   containerd or Docker APIs to create and manage containers yourself.
   These containers are not marked required, so it's up to a user to take
   action to terminate a VM on container failure.
 Instances that are running can be accessed via the region ingress.
 Endpoints per exposed service are returned as part of the instance
 creation. For example, proxies are exposed that allow direct access to
 `containerd`, `docker`, etc services which are usually only exposed over
 Unix sockets.
 The creation of an instance produces a set of metadata: InstanceMetadata
 is also available in ListInstances requests, but the remainder of
 metadata (e.g. extended metadata) is only available at creation time, or
 if DescribeInstance is called.
 Instance creation is non-blocking. After an instance is created call
 WaitInstance to observe the states instance creation goes through.
 ### Errors
 - If the workspace is out of resources, a `ResourceExhausted` status is
   returned.
 - If the request refers to an invalid argument, e.g. a non-existing
   region, an `InvalidArgument` status is returned.

    • waitInstanceSync

      public com.google.common.util.concurrent.ListenableFuture<Compute.WaitInstanceResponse> waitInstanceSync(Compute.WaitInstanceRequest request)
       Waits until an instance reaches the RUNNING state and returns the
 instance metadata.
 To receive intermediate state updates during instance creation process
 use the streaming version of this method — `WaitInstance`.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.

    • extendInstance

      public com.google.common.util.concurrent.ListenableFuture<Compute.ExtendInstanceResponse> extendInstance(Compute.ExtendInstanceRequest request)
       Extend the lifetime of an instance by the provided duration.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.

    • startContainers

      public com.google.common.util.concurrent.ListenableFuture<Compute.StartContainersResponse> startContainers(Compute.StartContainersRequest request)
       Adds the specified set of containers to a running instance.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.

    • describeInstance

      public com.google.common.util.concurrent.ListenableFuture<Compute.DescribeInstanceResponse> describeInstance(Compute.DescribeInstanceRequest request)
       Obtains the metadata (including extra metadata) of a previously created
 instance.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.

    • destroyInstance

      public com.google.common.util.concurrent.ListenableFuture<com.google.protobuf.Empty> destroyInstance(Compute.DestroyInstanceRequest request)
       Destroys a previously created instance.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.

    • listInstances

      public com.google.common.util.concurrent.ListenableFuture<Compute.ListInstancesResponse> listInstances(Compute.ListInstancesRequest request)
       Returns a list of all instances that match the specified filter.

    • suspendInstance

      public com.google.common.util.concurrent.ListenableFuture<com.google.protobuf.Empty> suspendInstance(Compute.SuspendInstanceRequest request)
       Request that the specified instance be suspended, i.e. it's execution is
 stopped and RAM and disks snapshotted in a way that can be restored
 without the instance being restarted.
 See WakeInstance for the counterpart.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.

    • wakeInstance

      public com.google.common.util.concurrent.ListenableFuture<com.google.protobuf.Empty> wakeInstance(Compute.WakeInstanceRequest request)
       Wakes up a suspended instance. Is a no-op if it is already running.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.
 - If the instance is not suspended, an `FailedPrecondition` status is returned.

    • createIngress

      public com.google.common.util.concurrent.ListenableFuture<Compute.CreateIngressResponse> createIngress(Compute.CreateIngressRequest request)
       Exposes a backend within the instance to the public internet. Typically
 used to serve public HTTPS-termination ingress that is backed by a
 container running inside the instance.
 See https://namespace.so/docs/architecture/networking/ingress for details.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.

    • listIngresses

      public com.google.common.util.concurrent.ListenableFuture<Compute.ListIngressesResponse> listIngresses(Compute.ListIngressesRequest request)
       Returns the list of backends exposed from the instance to the public
 internet. This includes ingresses created using `CreateIngress` above
 or ingresses declaratively exposed using FEATURE_KUBERNETES_INGRESS_MANAGER
 feature.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.
 - If the instance is already terminated, a `FailedPrecondition`
   status is returned.

    • getKubernetesConfig

      public com.google.common.util.concurrent.ListenableFuture<Compute.GetKubernetesConfigResponse> getKubernetesConfig(Compute.GetKubernetesConfigRequest request)
       Returns a configuration that can be used by `kubectl` to access
 Kubernetes inside the specified instance.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.
 - If the instance is not running Kubernetes, an `FailedPrecondition`
   status is returned.

    • getInstanceMetrics

      public com.google.common.util.concurrent.ListenableFuture<Compute.GetInstanceMetricsResponse> getInstanceMetrics(Compute.GetInstanceMetricsRequest request)
       Returns metrics that represent resource usage by the specified instance.
 Metrics can also be queried from instances that are still running.
 See https://namespace.so/docs/architecture/compute/observability for details.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.

    • getNetworkConfiguration

      public com.google.common.util.concurrent.ListenableFuture<Compute.GetNetworkConfigurationResponse> getNetworkConfiguration(Compute.GetNetworkConfigurationRequest request)
       Returns the network configuration used within the target workspace.
 See https://namespace.so/docs/architecture/networking for details.

    • getSSHConfig

      public com.google.common.util.concurrent.ListenableFuture<Compute.GetSSHConfigResponse> getSSHConfig(Compute.GetSSHConfigRequest request)
       Returns a configuration that can be used to access the instance with SSH.
 See https://namespace.so/docs/architecture/compute/ssh-remote-display for details.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.

    • getVNCConfig

      public com.google.common.util.concurrent.ListenableFuture<Compute.GetVNCConfigResponse> getVNCConfig(Compute.GetVNCConfigRequest request)
       Returns a configuration that can be used to access the instance's remote display using VNC.
 The caller's authentication token must also grant access to the instance ingress when connecting to the returned endpoint.
 ### Errors
 - If the instance does not exist, a `NotFound` status is returned.
 - If the instance does not expose a VNC service, a `FailedPrecondition` status is returned.

    • releaseUniqueTag

      public com.google.common.util.concurrent.ListenableFuture<Compute.ReleaseUniqueTagResponse> releaseUniqueTag(Compute.ReleaseUniqueTagRequest request)
       Release the currently associated instance ID from a unique tag.
 Tags are only unique per region. Make sure to select the correct ComputeService endpoint.
 When calling this service from within an instance, `NSC_ENDPOINT` will point to the ComputeService endpoint for the current region.
 Our [SDK](https://github.com/namespacelabs/integrations?tab=readme-ov-file#namespace-integrations) handles this automatically.
 ### Errors
 - If the unique tag does not exist, a `NotFound` status is returned.

    • listInstanceNotifications

      public com.google.common.util.concurrent.ListenableFuture<Compute.ListInstanceNotificationsResponse> listInstanceNotifications(Compute.ListInstanceNotificationsRequest request)
       Returns a list of instance notification events. Each instance has at most one event
 in the response, representing its most recent state change. Events can
 be filtered by instance ID.