# `Observatory` An `Observatory` is the building and the site: the roof, the weather, and the location. `observatory-operator` runs one INDI server for the devices that no telescope owns, such as the `Dome` and the `WeatherStation`, while at least one `Reservation` of a telescope here is active. ## spec The site. | Field | Type | Required | Description | | --- | --- | --- | --- | | `location` | [object](#speclocation) | yes | Where the site is. The operator writes it to each mount and GPS as `GEOGRAPHIC_COORD`, which takes the longitude from 0 to 360 degrees east, and converts a negative longitude to that range. | | `activation` | [\[\]object](#specactivation) | no | The actions that run, in order, as this resource's `Telescope` or `Observatory` turns `Active`, while every device is still connected. For a `Telescope` or an `Observatory`, that is the resource itself. The `Reservation`'s `Activation` step waits for them. Each action is a target state, so a run that an operator restart interrupted runs again each action that is not `Done`. Optional. | | `deactivation` | [\[\]object](#specdeactivation) | no | The actions that run, in order, as this resource's `Telescope` or `Observatory` stops being `Active`, while every device is still connected. For a `Telescope` or an `Observatory`, that is the resource itself. The `Reservation`'s `Deactivation` step waits for them. Each action is a target state, so a run that an operator restart interrupted runs again each action that is not `Done`. Optional. | | `triggers` | [\[\]object](#spectriggers) | no | Triggers on conditions. Each one runs its actions once for each transition of its condition to the status it names, while the resource is active: from when its activation is done until its deactivation begins. A condition that holds when the activation ends runs then. A run that began runs to its end, unless the resource's deactivation begins, and a resource runs one procedure at a time. Optional. | ### spec.location Where the site is. The operator writes it to each mount and GPS as `GEOGRAPHIC_COORD`, which takes the longitude from 0 to 360 degrees east, and converts a negative longitude to that range. | Field | Type | Required | Description | | --- | --- | --- | --- | | `latitude` | number | yes | The latitude, in degrees north, from -90 to 90. | | `longitude` | number | yes | The longitude, in degrees east, from -180 to 180. A site west of Greenwich has a negative longitude. | | `elevation` | number | yes | The elevation, in meters above mean sea level. | ### spec.activation[] One action, which names `job`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `job` | [object](#specactivationjob) | no | A container that the operator runs once as a Kubernetes `Job` in the resource's namespace, for what no other action does, such as switching a dew heater's relay or posting to a webhook. The resource owns the `Job`. The action is `Done` when the `Job` succeeds, and `Failed` with the `Job`'s reason and message when it fails. The `Job` has no retry, and its `activeDeadlineSeconds` is the action's timeout. Kubernetes deletes it an hour after it ends. The environment adds `LIKEN_OBSERVATORY`, `LIKEN_TELESCOPE` for a resource of a telescope, `LIKEN_RESOURCE` such as `Dome/lab`, `LIKEN_TRIGGER` such as `activation` or `triggers[0]`, and `INDI_HOST` and `INDI_PORT` of the resource's INDI server. The container runs as user 1000 with no capabilities, on a read-only root filesystem with a writable `/tmp`. The default timeout is 10 minutes. | | `timeout` | string | no | How long the action may take, its waits for `requires` and `after` included, as a duration such as `20m`. An action that passes it fails. Optional. Each action has a default. | | `requires` | [\[\]object](#specactivationrequires) | no | The conditions that must hold before the action runs. The operator waits for each one until the action's timeout. They bind only the actions that the operator runs: a move that a person makes in KStars is stopped only by the drivers' park locks. | | `after` | [\[\]object](#specactivationafter) | no | The resources whose runs for the same event must end before the action runs: the same lifecycle step, or the same transition of the same condition. A resource with no such run is not waited for. A resource in a later tier of the tree is waited for until the action's timeout, and the action then fails. | #### spec.activation[].job A container that the operator runs once as a Kubernetes `Job` in the resource's namespace, for what no other action does, such as switching a dew heater's relay or posting to a webhook. The resource owns the `Job`. The action is `Done` when the `Job` succeeds, and `Failed` with the `Job`'s reason and message when it fails. The `Job` has no retry, and its `activeDeadlineSeconds` is the action's timeout. Kubernetes deletes it an hour after it ends. The environment adds `LIKEN_OBSERVATORY`, `LIKEN_TELESCOPE` for a resource of a telescope, `LIKEN_RESOURCE` such as `Dome/lab`, `LIKEN_TRIGGER` such as `activation` or `triggers[0]`, and `INDI_HOST` and `INDI_PORT` of the resource's INDI server. The container runs as user 1000 with no capabilities, on a read-only root filesystem with a writable `/tmp`. The default timeout is 10 minutes. | Field | Type | Required | Description | | --- | --- | --- | --- | | `image` | string | yes | The container image, used as written, such as `busybox:1.37`. | | `command` | []string | no | The command that replaces the image's entrypoint, as a container's `command` does. Optional. | | `args` | []string | no | The arguments of the command, as a container's `args` are. Optional. | | `env` | [\[\]object](#specactivationjobenv) | no | Variables that the operator adds to the container's environment before its own, as `{name, value}`. A variable that has the name of one of the operator's own is replaced by the operator's. Optional. | #### spec.activation[].job.env[] One variable. | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | The variable's name, such as `RELAY_URL`. Pattern: `^[-._a-zA-Z][-._a-zA-Z0-9]*$`. | | `value` | string | yes | The variable's value. It can be empty. | #### spec.activation[].requires[] One condition, and the status it must have. | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | string | no | The kind of the resource whose condition it reads. With no `kind`, the condition is the resource's own. A `kind` of `Observatory` or `Telescope` with no `name` means the resource's own observatory or telescope. One of: `Observatory`, `Telescope`, `OpticalTube`, `OpticalTrain`, `Mount`, `Camera`, `FilterWheel`, `Focuser`, `Rotator`, `DustCap`, `FlatPanel`, `PolarAligner`, `GPS`, `Dome`, `WeatherStation`, `SkyQualityMeter`, `Switch`, `Receiver`, `Guider`. | | `name` | string | no | The name of the resource, in this namespace. A device kind needs a name. Pattern: `^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$`. | | `type` | string | yes | The condition's type, such as `Safe` or `Parked`. | | `status` | string | no | The status that the condition must have: `True`, `False`, or `Unknown`. The default is `True`. One of: `True`, `False`, `Unknown`. Default: `True`. | #### spec.activation[].after[] One resource, by its kind and name. | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | string | yes | The kind of the resource. One of: `Observatory`, `Telescope`, `OpticalTube`, `OpticalTrain`, `Mount`, `Camera`, `FilterWheel`, `Focuser`, `Rotator`, `DustCap`, `FlatPanel`, `PolarAligner`, `GPS`, `Dome`, `WeatherStation`, `SkyQualityMeter`, `Switch`, `Receiver`, `Guider`. | | `name` | string | no | The name of the resource. With no `name`, the reference names every resource of the kind in the observatory, or the resource's own `Observatory` or `Telescope`. Pattern: `^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$`. | ### spec.deactivation[] One action, which names `job`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `job` | [object](#specdeactivationjob) | no | A container that the operator runs once as a Kubernetes `Job` in the resource's namespace, for what no other action does, such as switching a dew heater's relay or posting to a webhook. The resource owns the `Job`. The action is `Done` when the `Job` succeeds, and `Failed` with the `Job`'s reason and message when it fails. The `Job` has no retry, and its `activeDeadlineSeconds` is the action's timeout. Kubernetes deletes it an hour after it ends. The environment adds `LIKEN_OBSERVATORY`, `LIKEN_TELESCOPE` for a resource of a telescope, `LIKEN_RESOURCE` such as `Dome/lab`, `LIKEN_TRIGGER` such as `activation` or `triggers[0]`, and `INDI_HOST` and `INDI_PORT` of the resource's INDI server. The container runs as user 1000 with no capabilities, on a read-only root filesystem with a writable `/tmp`. The default timeout is 10 minutes. | | `timeout` | string | no | How long the action may take, its waits for `requires` and `after` included, as a duration such as `20m`. An action that passes it fails. Optional. Each action has a default. | | `requires` | [\[\]object](#specdeactivationrequires) | no | The conditions that must hold before the action runs. The operator waits for each one until the action's timeout. They bind only the actions that the operator runs: a move that a person makes in KStars is stopped only by the drivers' park locks. | | `after` | [\[\]object](#specdeactivationafter) | no | The resources whose runs for the same event must end before the action runs: the same lifecycle step, or the same transition of the same condition. A resource with no such run is not waited for. A resource in a later tier of the tree is waited for until the action's timeout, and the action then fails. | #### spec.deactivation[].job A container that the operator runs once as a Kubernetes `Job` in the resource's namespace, for what no other action does, such as switching a dew heater's relay or posting to a webhook. The resource owns the `Job`. The action is `Done` when the `Job` succeeds, and `Failed` with the `Job`'s reason and message when it fails. The `Job` has no retry, and its `activeDeadlineSeconds` is the action's timeout. Kubernetes deletes it an hour after it ends. The environment adds `LIKEN_OBSERVATORY`, `LIKEN_TELESCOPE` for a resource of a telescope, `LIKEN_RESOURCE` such as `Dome/lab`, `LIKEN_TRIGGER` such as `activation` or `triggers[0]`, and `INDI_HOST` and `INDI_PORT` of the resource's INDI server. The container runs as user 1000 with no capabilities, on a read-only root filesystem with a writable `/tmp`. The default timeout is 10 minutes. | Field | Type | Required | Description | | --- | --- | --- | --- | | `image` | string | yes | The container image, used as written, such as `busybox:1.37`. | | `command` | []string | no | The command that replaces the image's entrypoint, as a container's `command` does. Optional. | | `args` | []string | no | The arguments of the command, as a container's `args` are. Optional. | | `env` | [\[\]object](#specdeactivationjobenv) | no | Variables that the operator adds to the container's environment before its own, as `{name, value}`. A variable that has the name of one of the operator's own is replaced by the operator's. Optional. | #### spec.deactivation[].job.env[] One variable. | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | The variable's name, such as `RELAY_URL`. Pattern: `^[-._a-zA-Z][-._a-zA-Z0-9]*$`. | | `value` | string | yes | The variable's value. It can be empty. | #### spec.deactivation[].requires[] One condition, and the status it must have. | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | string | no | The kind of the resource whose condition it reads. With no `kind`, the condition is the resource's own. A `kind` of `Observatory` or `Telescope` with no `name` means the resource's own observatory or telescope. One of: `Observatory`, `Telescope`, `OpticalTube`, `OpticalTrain`, `Mount`, `Camera`, `FilterWheel`, `Focuser`, `Rotator`, `DustCap`, `FlatPanel`, `PolarAligner`, `GPS`, `Dome`, `WeatherStation`, `SkyQualityMeter`, `Switch`, `Receiver`, `Guider`. | | `name` | string | no | The name of the resource, in this namespace. A device kind needs a name. Pattern: `^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$`. | | `type` | string | yes | The condition's type, such as `Safe` or `Parked`. | | `status` | string | no | The status that the condition must have: `True`, `False`, or `Unknown`. The default is `True`. One of: `True`, `False`, `Unknown`. Default: `True`. | #### spec.deactivation[].after[] One resource, by its kind and name. | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | string | yes | The kind of the resource. One of: `Observatory`, `Telescope`, `OpticalTube`, `OpticalTrain`, `Mount`, `Camera`, `FilterWheel`, `Focuser`, `Rotator`, `DustCap`, `FlatPanel`, `PolarAligner`, `GPS`, `Dome`, `WeatherStation`, `SkyQualityMeter`, `Switch`, `Receiver`, `Guider`. | | `name` | string | no | The name of the resource. With no `name`, the reference names every resource of the kind in the observatory, or the resource's own `Observatory` or `Telescope`. Pattern: `^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$`. | ### spec.triggers[] One trigger: a condition, and the actions it runs. | Field | Type | Required | Description | | --- | --- | --- | --- | | `when` | [object](#spectriggerswhen) | yes | The condition, and the status that fires the trigger. | | `run` | [\[\]object](#spectriggersrun) | yes | The actions that run, in order. | #### spec.triggers[].when The condition, and the status that fires the trigger. | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | string | no | The kind of the resource whose condition it reads. With no `kind`, the condition is the resource's own. A `kind` of `Observatory` or `Telescope` with no `name` means the resource's own observatory or telescope. One of: `Observatory`, `Telescope`, `OpticalTube`, `OpticalTrain`, `Mount`, `Camera`, `FilterWheel`, `Focuser`, `Rotator`, `DustCap`, `FlatPanel`, `PolarAligner`, `GPS`, `Dome`, `WeatherStation`, `SkyQualityMeter`, `Switch`, `Receiver`, `Guider`. | | `name` | string | no | The name of the resource, in this namespace. A device kind needs a name. Pattern: `^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$`. | | `type` | string | yes | The condition's type, such as `Safe` or `Parked`. | | `status` | string | no | The status that the condition must have: `True`, `False`, or `Unknown`. The default is `True`. One of: `True`, `False`, `Unknown`. Default: `True`. | | `for` | string | no | How long the status must hold before the actions run, as a duration such as `20m`. A change of the status before then cancels the run. Optional. | #### spec.triggers[].run[] One action, which names `job`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `job` | [object](#spectriggersrunjob) | no | A container that the operator runs once as a Kubernetes `Job` in the resource's namespace, for what no other action does, such as switching a dew heater's relay or posting to a webhook. The resource owns the `Job`. The action is `Done` when the `Job` succeeds, and `Failed` with the `Job`'s reason and message when it fails. The `Job` has no retry, and its `activeDeadlineSeconds` is the action's timeout. Kubernetes deletes it an hour after it ends. The environment adds `LIKEN_OBSERVATORY`, `LIKEN_TELESCOPE` for a resource of a telescope, `LIKEN_RESOURCE` such as `Dome/lab`, `LIKEN_TRIGGER` such as `activation` or `triggers[0]`, and `INDI_HOST` and `INDI_PORT` of the resource's INDI server. The container runs as user 1000 with no capabilities, on a read-only root filesystem with a writable `/tmp`. The default timeout is 10 minutes. | | `timeout` | string | no | How long the action may take, its waits for `requires` and `after` included, as a duration such as `20m`. An action that passes it fails. Optional. Each action has a default. | | `requires` | [\[\]object](#spectriggersrunrequires) | no | The conditions that must hold before the action runs. The operator waits for each one until the action's timeout. They bind only the actions that the operator runs: a move that a person makes in KStars is stopped only by the drivers' park locks. | | `after` | [\[\]object](#spectriggersrunafter) | no | The resources whose runs for the same event must end before the action runs: the same lifecycle step, or the same transition of the same condition. A resource with no such run is not waited for. A resource in a later tier of the tree is waited for until the action's timeout, and the action then fails. | #### spec.triggers[].run[].job A container that the operator runs once as a Kubernetes `Job` in the resource's namespace, for what no other action does, such as switching a dew heater's relay or posting to a webhook. The resource owns the `Job`. The action is `Done` when the `Job` succeeds, and `Failed` with the `Job`'s reason and message when it fails. The `Job` has no retry, and its `activeDeadlineSeconds` is the action's timeout. Kubernetes deletes it an hour after it ends. The environment adds `LIKEN_OBSERVATORY`, `LIKEN_TELESCOPE` for a resource of a telescope, `LIKEN_RESOURCE` such as `Dome/lab`, `LIKEN_TRIGGER` such as `activation` or `triggers[0]`, and `INDI_HOST` and `INDI_PORT` of the resource's INDI server. The container runs as user 1000 with no capabilities, on a read-only root filesystem with a writable `/tmp`. The default timeout is 10 minutes. | Field | Type | Required | Description | | --- | --- | --- | --- | | `image` | string | yes | The container image, used as written, such as `busybox:1.37`. | | `command` | []string | no | The command that replaces the image's entrypoint, as a container's `command` does. Optional. | | `args` | []string | no | The arguments of the command, as a container's `args` are. Optional. | | `env` | [\[\]object](#spectriggersrunjobenv) | no | Variables that the operator adds to the container's environment before its own, as `{name, value}`. A variable that has the name of one of the operator's own is replaced by the operator's. Optional. | #### spec.triggers[].run[].job.env[] One variable. | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | The variable's name, such as `RELAY_URL`. Pattern: `^[-._a-zA-Z][-._a-zA-Z0-9]*$`. | | `value` | string | yes | The variable's value. It can be empty. | #### spec.triggers[].run[].requires[] One condition, and the status it must have. | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | string | no | The kind of the resource whose condition it reads. With no `kind`, the condition is the resource's own. A `kind` of `Observatory` or `Telescope` with no `name` means the resource's own observatory or telescope. One of: `Observatory`, `Telescope`, `OpticalTube`, `OpticalTrain`, `Mount`, `Camera`, `FilterWheel`, `Focuser`, `Rotator`, `DustCap`, `FlatPanel`, `PolarAligner`, `GPS`, `Dome`, `WeatherStation`, `SkyQualityMeter`, `Switch`, `Receiver`, `Guider`. | | `name` | string | no | The name of the resource, in this namespace. A device kind needs a name. Pattern: `^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$`. | | `type` | string | yes | The condition's type, such as `Safe` or `Parked`. | | `status` | string | no | The status that the condition must have: `True`, `False`, or `Unknown`. The default is `True`. One of: `True`, `False`, `Unknown`. Default: `True`. | #### spec.triggers[].run[].after[] One resource, by its kind and name. | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | string | yes | The kind of the resource. One of: `Observatory`, `Telescope`, `OpticalTube`, `OpticalTrain`, `Mount`, `Camera`, `FilterWheel`, `Focuser`, `Rotator`, `DustCap`, `FlatPanel`, `PolarAligner`, `GPS`, `Dome`, `WeatherStation`, `SkyQualityMeter`, `Switch`, `Receiver`, `Guider`. | | `name` | string | no | The name of the resource. With no `name`, the reference names every resource of the kind in the observatory, or the resource's own `Observatory` or `Telescope`. Pattern: `^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$`. | ## status What the operator observes. The operator writes it, and a person reads it. | Field | Type | Required | Description | | --- | --- | --- | --- | | `observedGeneration` | integer | no | The `metadata.generation` of the spec that the operator last acted on. | | `phase` | string | no | The state in one word. `Idle`: no reservation needs it, and nothing runs. `Activating`: a reservation's activation steps run. `Ready`: everything it needs runs and is connected. `Deactivating`: a reservation's deactivation steps run. `Error`: a step failed, and the `Ready` condition gives the reason. The observatory's server runs from the first active reservation here to the end of the last one. One of: `Idle`, `Activating`, `Ready`, `Deactivating`, `Error`. | | `procedures` | [\[\]object](#statusprocedures) | no | The last run of each trigger of the resource's procedures: `activation`, `deactivation`, and `triggers[0]` and so on for each item of `spec.triggers`. An operator that restarts resumes a run from this record. | | `conditions` | [\[\]object](#statusconditions) | no | `Ready` is `True` while the observatory's server and devices run and are connected. `LocksRelayed` is present while the observatory has a `Dome`. It is `True` while the operator relays the park states that the locks need, `False` with the reason `Waiting` while a dome or a mount does not report what the relay needs, and `False` with the reason `Idle` while no dome or mount runs. `Active` is `True` from the `Activation` step of the first reservation in the observatory until the `Deactivation` step of the last one. Its `lastTransitionTime` is the transition that starts the activation and deactivation procedures. | | `server` | [object](#statusserver) | no | The observatory's own INDI server, while it runs. | | `telescopes` | []string | no | Each `Telescope` whose `spec.observatory` names this observatory. | | `devices` | [\[\]object](#statusdevices) | no | Each device whose parent is this observatory. | | `reservations` | []string | no | Each active `Reservation` of a telescope here. | | `display` | [object](#statusdisplay) | no | The spec as a person reads it, with its units, for the printer columns. | | `weather` | string | no | The worst safety status of the observatory's weather stations, or `Unknown` when no station reports. One of: `Safe`, `Warning`, `Danger`, `Unknown`. | ### status.procedures[] The last run of one trigger. | Field | Type | Required | Description | | --- | --- | --- | --- | | `trigger` | string | yes | The trigger: `activation`, `deactivation`, or `triggers[0]` for the first item of `spec.triggers`. | | `since` | string | no | The transition time of the condition that started the run: the `lastTransitionTime` of `Active` for activation and deactivation. | | `state` | string | yes | The run's progress: `Pending`, `Running`, `Done`, `Failed`, or `Skipped` when it had nothing to do. One of: `Pending`, `Running`, `Done`, `Failed`, `Skipped`. | | `startTime` | string | no | When the run began to run. | | `stopTime` | string | no | When the run ended. | | `summary` | string | no | What the run waits for or did. | | `actions` | [\[\]object](#statusproceduresactions) | no | Each action of the run, in order. | #### status.procedures[].actions[] One action. | Field | Type | Required | Description | | --- | --- | --- | --- | | `action` | string | yes | The action as its YAML reads, such as `state: Parked` or `cool: -10 °C within 0.5 °C`. | | `state` | string | yes | The action's progress: `Pending`, `Running`, `Done`, `Failed`, or `Skipped` when it had nothing to do. One of: `Pending`, `Running`, `Done`, `Failed`, `Skipped`. | | `startTime` | string | no | When the action began to run. | | `stopTime` | string | no | When the action ended. | | `summary` | string | no | What the action waits for or did. | ### status.conditions[] One condition, in the shape of `metav1.Condition`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | string | yes | The condition's name, such as `Ready`. | | `status` | string | yes | Whether the condition holds: `True`, `False`, or `Unknown`. One of: `True`, `False`, `Unknown`. | | `observedGeneration` | integer | no | The `metadata.generation` of the spec that the condition reflects. | | `reason` | string | yes | One word in CamelCase for the cause. | | `message` | string | yes | The cause, for a person to read. It can be empty. | | `lastTransitionTime` | string | yes | When `status` last changed. A write with the same status keeps this time. | ### status.server The observatory's own INDI server, while it runs. | Field | Type | Required | Description | | --- | --- | --- | --- | | `service` | string | yes | The name of the server's `Service`. | | `host` | string | yes | The `Service`'s DNS name in the cluster. | | `port` | integer | yes | The INDI port of the `Service`, 7624. | | `pod` | string | no | The name of the server's pod. | | `node` | string | no | The node that runs the server's pod. | ### status.devices[] One device, with its phase. | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | string | yes | The device's kind. One of: `Mount`, `Camera`, `FilterWheel`, `Focuser`, `Rotator`, `DustCap`, `FlatPanel`, `PolarAligner`, `GPS`, `Dome`, `WeatherStation`, `SkyQualityMeter`, `Switch`, `Receiver`. | | `name` | string | yes | The device's name. | | `phase` | string | no | The device's `status.phase`. One of: `Inventory`, `Idle`, `Starting`, `Connecting`, `Connected`, `Disconnecting`, `Error`. | ### status.display The spec as a person reads it, with its units, for the printer columns. | Field | Type | Required | Description | | --- | --- | --- | --- | | `latitude` | string | no | The latitude in degrees north or south, such as `51.4769° N`. | | `longitude` | string | no | The longitude in degrees east or west, such as `0.0005° W`. |