> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-references/rest-messaging-api/rest-messaging-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](#names) that is unique for that type of resource. Every StreamNative Cloud object also has a [UID](#uids) 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](https://tools.ietf.org/html/rfc1123).
  * 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](https://tools.ietf.org/html/rfc1123).
  * 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 `spec`object for a cluster in StreamNative Cloud.

```yaml theme={null}
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.

```shell theme={null}
snctl apply -f /path/to/clusterneo1.yaml
```

The output is similar to this:

```sh theme={null}
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.

```sh theme={null}
snctl create pulsarinstances neo
```