High Availability Checkin [Internal API]

components/schemas/containers/Container.yml

@@ -13,6 +13,9 @@ required:
   - instances
   - stateful
   - state
+  - role
+  - ha
+  - deployment
   - deprecate
   - lock
   - events
@@ -63,6 +66,11 @@ properties:
         enum:
           - orchestrator
       - type: "null"
+  ha:
+    description: High availability status of the container. Contains information about the primary instance, if any.
+    oneOf:
+      - $ref: ./ha/ContainerHighAvailability.yml
+      - type: "null"
   stateful:
     type: boolean
     description: A boolean where true signifies the container is stateful.

components/schemas/containers/config/ContainerDeploy.yml

@@ -12,6 +12,11 @@ properties:
       - $ref: ../../infrastructure/DeploymentStrategyName.yml
       - type: "null"
     description: The deployment strategy to use when scaling the given container.
+  ha:
+    description: Configuration options for how the platform treats instances of this container when opting into high availability via the internal API.
+    oneOf:
+      - $ref: ./deploy/ContainerDeployHighAvailabilityConfig.yml
+      - type: "null"
   function:
     description: Configuration options for containers using the 'function' deployment strategy.
     oneOf:

components/schemas/containers/config/deploy/ContainerDeployHighAvailabilityConfig.yml

@@ -0,0 +1,10 @@
+title: ContainerDeployHighAvailabilityConfig
+description: Configuration options for how the platform treats instances of this container when opting into high availability via the internal API.
+required:
+  - stale_primary_deadline
+properties:
+  stale_primary_deadline:
+    description: The amount of time that must pass between high availability checkins before an instance is considered stale. If it is the primary, a new primary will be elected after this deadline. Minimum is 15s.
+    oneOf:
+      - $ref: ../../../Duration.yml
+      - type: "null"

components/schemas/containers/ha/ContainerHighAvailability.yml

@@ -0,0 +1,17 @@
+title: ContainerHighAvailability
+description: |
+  The high availability configuration and status for a container, as determined by the platform.
+type: object
+required:
+  - last_checkin
+  - primary
+properties:
+  last_checkin:
+    description: The last time the primary checked in.
+    $ref: ../../DateTime.yml
+  primary:
+    description: |
+      Information about the instance currently elected as the primary for this container. Null when no primary has been elected.
+    oneOf:
+      - $ref: "./ContainerHighAvailabilityPrimary.yml"
+      - type: "null"

components/schemas/containers/ha/ContainerHighAvailabilityPrimary.yml

@@ -0,0 +1,23 @@
+title: ContainerHighAvailabilityPrimary
+description: |
+  Details about the instance currently elected as the high availability primary for a container.
+type: object
+required:
+  - instance_id
+  - priority
+  - elected
+  - last_checkin
+properties:
+  instance_id:
+    description: The ID of the instance that has been elected as the primary.
+    $ref: "../../ID.yml"
+  priority:
+    type: integer
+    format: int32
+    description: The priority value assigned to this instance for the election. Higher priority means more likely to be elected primary.
+  elected:
+    description: The time at which this instance was elected as the primary.
+    $ref: "../../DateTime.yml"
+  last_checkin:
+    description: The time the primary instance last checked into the high availability service.
+    $ref: "../../DateTime.yml"

components/schemas/containers/instances/Instance.yml

@@ -102,6 +102,10 @@ properties:
     anyOf:
       - $ref: ../Deployment.yml
       - type: "null"
+  ha:
+    oneOf:
+      - $ref: ./InstanceHighAvailability.yml
+      - type: "null"
   events:
     title: InstanceEvents
     description: A collection of timestamps for each event in the instance's lifetime.

components/schemas/containers/instances/InstanceHighAvailability.yml

@@ -0,0 +1,17 @@
+title: InstanceHighAvailability
+description: |
+  The high availability status of the instance, as determined by the platform. 
+
+  This data becomes avaialble when utilizing the internal API high availability endpoint. The platform will hold elections for all instances hitting the endpoint and choose a primary. As long as those instances continue to check in, the primary will continue to be the primary until it is dropped off. After which, a secondary will be promoted.
+type: object
+required:
+  - last_checkin
+properties:
+  elected_primary:
+    description: If a time is set, indicates that this instance is the primary, and the time at which it was promoted.
+    oneOf:
+      - $ref: "../../DateTime.yml"
+      - type: "null"
+  last_checkin:
+    description: The time that the instance last checked into the HA service.
+    $ref: "../../DateTime.yml"

components/schemas/containers/summaries/ContainerSummary.yml

@@ -38,6 +38,11 @@ properties:
       - type: "null"
   state:
     $ref: "../ContainerState.yml"
+  ha:
+    description: High availability status of the container. Contains information about the primary instance, if any.
+    oneOf:
+      - $ref: ../ha/ContainerHighAvailability.yml
+      - type: "null"
   role:
     type:
       - string

internal/api.yml

@@ -84,6 +84,10 @@ paths:
   /v1/conductor/tasks:
     $ref: paths/conductor/tasks.yml
 
+  # HA
+  /v1/ha/checkin:
+    $ref: paths/ha/checkin.yml
+
   # Monitoring
   /v1/monitoring/metrics:
     $ref: paths/monitoring/metrics.yml
@@ -101,7 +105,7 @@ paths:
     $ref: paths/sdn/instances.yml
   /v1/sdn/networks/environments:
     $ref: paths/sdn/environments.yml
-  
+
   # Virtual Machines
   /v1/virtual-machine:
     $ref: paths/virtual-machine/virtual-machine.yml
@@ -110,7 +114,6 @@ paths:
   /v1/virtual-machine/gateways:
     $ref: paths/virtual-machine/gateways.yml
 
-
   # Object Cache
   /v1/object-cache:
     $ref: paths/object-cache/object-cache.yml

internal/paths/environment/containers.yml

@@ -4,7 +4,6 @@ get:
   description: Lists all Containers that are part of the same Environment as this Instance.
   tags:
     - Environments
-    - Containers
   parameters: []
   responses:
     default:

internal/paths/environment/scoped-variables.yml

@@ -4,7 +4,6 @@ get:
   description: |
     Gets the scoped variables that are accessible to this instance via internal API.
   tags:
-    - Environments
     - Scoped Variables
   parameters: []
   responses:

internal/paths/ha/checkin.yml

@@ -0,0 +1,51 @@
+post:
+  operationId: highAvailabilityCheckin
+  summary: High Availability Checkin
+  description: |
+    Hit this endpoint every 30 seconds to check in and have the platform select and maintain a primary instance.
+    Every instance you wish to be considered for a primary should hit this endpoint roughly every 30 seconds. The platform will choose one instance as the primary, and it will continue to be the primary until it stops checking in. If a primary stops checking in, a secondary will be selected to be promoted to primary.
+  tags:
+    - High Availability
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          required:
+            - electable
+            - priority
+          properties:
+            electable:
+              type: boolean
+              description: Whether this instance wishes to be considered for election as the primary.
+            priority:
+              type: integer
+              format: int32
+              description: The election priority for this instance. Higher priority means more likely to be elected primary.
+  responses:
+    "200":
+      description: Returns the result of the high availability check-in.
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - data
+            properties:
+              data:
+                type: object
+                required:
+                  - time
+                  - primary_instance_id
+                properties:
+                  time:
+                    description: The time the platform recorded this check-in.
+                    $ref: "../../../components/schemas/DateTime.yml"
+                  primary_instance_id:
+                    description: The ID of the instance currently elected as the primary. Null when no primary has been elected yet.
+                    oneOf:
+                      - $ref: "../../../components/schemas/ID.yml"
+                      - type: "null"
+    default:
+      $ref: ../../../components/responses/errors/DefaultError.yml

stackspec/schema/StackSpecContainer.yml

@@ -11,7 +11,6 @@ properties:
     type: string
     description: The human-readable name of this container.
   image:
-    x-ogen-name: StackSpecContainerImageProperty
     description: Details about the image used for this container.
     oneOf:
       - $ref: StackSpecContainerImage.yml

stackspec/schema/StackSpecContainerConfigDeploy.yml

@@ -35,6 +35,12 @@ properties:
       - type: "null"
       - $ref: StackVariable.yml
 
+  ha:
+    oneOf:
+      - $ref: ./deploy/StackSpecContainerConfigHighAvailability.yml
+      - type: "null"
+      - $ref: StackVariable.yml
+
   function:
     description: Configuration options for containers using the 'function' deployment strategy.
     oneOf:

stackspec/schema/StackVariable.yml

@@ -3,4 +3,5 @@ description: A variable specified in a stack spec.
 pattern: '"?\{\{(\$)?([a-z0-9-]+)\}\}"?'
 type: string
 examples:
+  - "{{stack-variable}}"
   - "{{$stack-variable}}"

stackspec/schema/deploy/StackSpecContainerConfigHighAvailability.yml

@@ -0,0 +1,10 @@
+title: StackSpecContainerConfigHighAvailability
+description: Configuration options for how the platform treats instances of this container when opting into high availability via the internal API.
+required:
+  - stale_primary_deadline
+properties:
+  stale_primary_deadline:
+    description: The amount of time that must pass between high availability checkins before an instance is considered stale. If it is the primary, a new primary will be elected after this deadline. Minimum is 15s.
+    oneOf:
+      - $ref: ../../../components/schemas/Duration.yml
+      - $ref: ../StackVariable.yml