Add endpoint support (#478)

* Add endpoint support

* Document endpoint network exposure

api/openapi.yaml

@@ -237,8 +237,10 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VM'
+        '400':
+          description: Invalid VM specification
         '409':
-          description: VM resource with with the same name already exists
+          description: VM resource with the same name already exists
     get:
       summary: "List VMs"
       tags:
@@ -311,6 +313,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VM'
+        '400':
+          description: Invalid VM specification
         '404':
           description: VM resource with the given name doesn't exist
     delete:
@@ -682,6 +686,19 @@ components:
           type: number
           description: Disk size for this VM
           example: 100
+        endpoints:
+          type: array
+          description: |
+            TCP services inside the VM to expose through TCP ports on the Orchard
+            Worker. The worker ports assigned to the endpoints are reported in
+            `observedEndpoints`.
+            Endpoint ports listen on all worker network interfaces. Use firewall
+            rules to restrict access.
+            VMs with endpoints are scheduled only on workers that support endpoint
+            forwarding. Adding endpoints to a VM already assigned to an unsupported
+            worker succeeds, but those endpoints are reported in the `error` state.
+          items:
+            $ref: '#/components/schemas/EndpointSpec'
         net-softnet:
           type: boolean
           description: Please use `netSoftnet` instead
@@ -854,6 +871,93 @@ components:
             Deprecated alias for `localName`.
           readOnly: true
           deprecated: true
+    ConnectionTarget:
+      title: Connection target
+      type: object
+      description: A connection destination relative to the containing resource or action.
+      required:
+        - vm
+      properties:
+        vm:
+          $ref: '#/components/schemas/ConnectionTargetVM'
+    ConnectionTargetVM:
+      title: VM connection target
+      type: object
+      required:
+        - port
+      properties:
+        port:
+          type: integer
+          minimum: 1
+          maximum: 65535
+          description: TCP port inside the contextual VM.
+    PortRange:
+      title: Port range
+      type: object
+      description: |
+        Inclusive bounds for selecting a network port. `min` must be less than or
+        equal to `max`; equal bounds identify one port.
+      required:
+        - min
+        - max
+      properties:
+        min:
+          type: integer
+          minimum: 1
+          maximum: 65535
+          description: Inclusive lower bound for port selection.
+        max:
+          type: integer
+          minimum: 1
+          maximum: 65535
+          description: Inclusive upper bound for port selection.
+    EndpointSpec:
+      title: Endpoint specification
+      type: object
+      description: A desired worker TCP endpoint backed by a connection target.
+      required:
+        - name
+        - target
+      properties:
+        name:
+          type: string
+          minLength: 1
+          description: Stable endpoint identifier, unique within `endpoints`.
+        target:
+          $ref: '#/components/schemas/ConnectionTarget'
+        workerPortRange:
+          description: |
+            Optional inclusive bounds for selecting the worker port. When omitted,
+            the operating system selects an available port. Equal bounds request
+            that exact port.
+          allOf:
+            - $ref: '#/components/schemas/PortRange'
+    EndpointStatus:
+      title: Endpoint status
+      type: object
+      description: Current observation for a desired endpoint.
+      required:
+        - name
+        - state
+      properties:
+        name:
+          type: string
+          minLength: 1
+          description: Stable endpoint identifier matching the desired endpoint.
+        workerPort:
+          type: integer
+          minimum: 1
+          maximum: 65535
+          description: TCP port assigned to this endpoint on the Orchard Worker.
+        state:
+          type: string
+          enum: [ listening, error ]
+          description: |
+            Exposure state. `listening` means that the worker TCP port is bound; it
+            does not imply that the service inside the VM is healthy or accepting connections.
+        message:
+          type: string
+          description: Human-readable detail, primarily populated when `state` is `error`.
     VMState:
       title: Virtual Machine State
       type: object
@@ -871,6 +975,13 @@ components:
         observedGeneration:
           type: number
           description: Corresponds to the `Generation` value on which the worker had acted upon
+        observedEndpoints:
+          type: array
+          readOnly: true
+          description: |
+            Current observations for the endpoints in `endpoints`.
+          items:
+            $ref: '#/components/schemas/EndpointStatus'
     Events:
       title: Events
       type: object