Understanding StreamNative Cloud objects

This document explains how StreamNative Cloud objects are represented in the StreamNative Cloud API, and how you can express them in .yaml format.

StreamNative Cloud objects are persistent entities in the StreamNative Cloud system. StreamNative Cloud uses these entities to represent the state of your organization. Specifically, they can describe:

• The containerized applications that are running (and on which nodes)
• The resources available to those applications
• The policies about the operation way for those applications

Once you create a StreamNative Cloud object, the StreamNative Cloud system constantly works to ensure that the object exists. To work with StreamNative Cloud objects, you need to use the StreamNative Cloud API. When you use the snctl CLI tool, the CLI tool makes the necessary StreamNative Cloud API calls for you.

Object names and IDs

Each object in your cluster has a name that is unique for that type of resource. Every StreamNative Cloud object also has a UID that is unique across your whole cluster. For example, you can only have one pod named myapp-1234 within the same organization.

Names

Below are three types of commonly used name constraints for resources.

• DNS subdomain names: most resources require a name that can be used as a DNS subdomain name as defined in RFC 1123.
  • Contain no more than 253 characters.
  • Contain only lowercase alphanumeric characters, '-' or '.'.
  • Start with an alphanumeric character.
  • End with an alphanumeric character.
• DNS label names: some resource types require their names to follow the DNS label standard as defined in RFC 1123.
  • Contain no more than 63 characters.
  • Contain only lowercase alphanumeric characters, '-'.
  • Start with an alphanumeric character.
  • End with an alphanumeric character.
• Path segment names: some resource types require their names to be able to be safely encoded as a path segment. In other words, the name might not be "." or ".." and the name might not contain "/" or "%".

UIDs

StreamNative Cloud UIDs are universally unique identifiers (also known as UUIDs). UUIDs are standardized as ISO/IEC 9834-8 and as ITU-T X.667.

Object spec and status

Almost every StreamNative Cloud object includes the spec and the status fields to govern the object's configuration. The spec field describes the desired characteristics of the object. The status describes the current state of the object, supplied and updated by the StreamNative Cloud system and its components. The StreamNative Cloud continually and actively manages every object's actual state.

Describe StreamNative Cloud objects

When you create an object in StreamNative Cloud, you must provide the spec field that describes its desired state, and some basic information about the object (such as a name). When you use the StreamNative Cloud API to create an object, that API request must include that information as JSON in the request body. Most often, you provide the information to snctl in a .yaml file. snctl converts the information to JSON when making the API request.

Here is an example of .yaml file that shows the required fields and the specobject for a cluster in StreamNative Cloud.

apiVersion: cloud.streamnative.io/v1alpha1
kind: PulsarCluster
metadata:
  namespace: matrix
  name: neo-1
spec:
  instanceName: neo
  location: us-east4
  broker:
    replicas: 1
  bookkeeper:
    replicas: 3

You can create a cluster by using the snctl apply command in the snctl CLI tool, passing the .yaml file as an argument. Here is an example.

snctl apply -f /path/to/clusterneo1.yaml

The output is similar to this:

cluster.cloud.streamnative.io/neo created

Required fields

In the .yaml file for the StreamNative Cloud object that you want to create, you need to set values for the following fields:

• apiVersion : specify the version of the StreamNative Cloud API used to create this object.
• kind: specify the object to be created.
• metadata: specify the data that helps uniquely identify the object, including a name string and a namespace string.
• spec - specify the state you desire for the object.

The precise format of the spec field is different for every StreamNative Cloud object, and contains nested fields specific to that object.

Manage StreamNative Cloud objects

The snctl CLI tool supports imperative commands to create and manage StreamNative Cloud objects. Imperative commands are simple, easy to learn and easy to remember. The imperative commands operate directly on live objects in an organization. You provide operations to the snctl command as arguments or flags. This is the simplest way to get started or to run a one-off task in an organization. Because this technique operates directly on live objects, it provides no history of previous configurations.

The following example shows how to create a cluster object neo using the imperative command.

snctl create pulsarinstances neo