Implement Gate API changes

specification/containerservice/Fleet.Management/gate.tsp

@@ -0,0 +1,182 @@
+import "@typespec/rest";
+import "./helpers.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.Rest;
+using TypeSpec.Versioning;
+using Azure.Core;
+using Azure.ResourceManager;
+using TypeSpec.OpenAPI;
+
+namespace Microsoft.ContainerService;
+
+@doc("A Gate controls the progression during a staged rollout, e.g. in an Update Run.")
+@added(Versions.v2025_04_01_preview)
+@resource("gate")
+@parentResource(Fleet)
+model Gate is ProxyResource<GateProperties> {
+  @doc("The name of the Gate resource, a GUID.")
+  @pattern("^[0-9a-f]{8}[-][0-9a-f]{4}[-][0-9a-f]{4}[-][0-9a-f]{4}[-][0-9a-f]{12}$")
+  @minLength(36)
+  @maxLength(36)
+  @key("gateName")
+  @path
+  @segment("gates")
+  @visibility(Lifecycle.Read)
+  name: string;
+
+  ...EntityTagProperty;
+}
+
+@doc("The type of the Gate determines how it is completed.")
+@added(Versions.v2025_04_01_preview)
+union GateType {
+  string,
+
+  @doc("An Approval Gate is completed by patching its status.")
+  Approval: "Approval",
+}
+
+@doc("The state of the Gate.")
+@added(Versions.v2025_04_01_preview)
+union GateState {
+  string,
+
+  @doc("A Pending Gate will continue to block the staged rollout process it is controlling.")
+  Pending: "Pending",
+
+  @doc("An Completed Gate allows the staged rollout process to continue.")
+  Completed: "Completed",
+}
+
+@doc("A Gate controls the progression during a staged rollout, e.g. in an Update Run.")
+@added(Versions.v2025_04_01_preview)
+model GateProperties {
+  // adding a response header in the model currently impacts the model used in the List result model.
+  // omitting it for now as response headers do not impact SDK generation.
+  // ...EtagResponseEnvelope;
+
+  @doc("The provisioning state of the Gate resource.")
+  @visibility(Lifecycle.Read)
+  provisioningState?: GateProvisioningState;
+
+  @doc("The human-readable display name of the Gate.")
+  @visibility(Lifecycle.Create, Lifecycle.Read)
+  @pattern("^[A-Za-z0-9].*$")
+  @minLength(1)
+  @maxLength(100)
+  displayName: string;
+
+  @doc("The target that the Gate is controlling, e.g. an Update Run.")
+  @visibility(Lifecycle.Create, Lifecycle.Read)
+  target: GateTarget;
+
+  @doc("The type of the Gate determines how it is completed.")
+  @visibility(Lifecycle.Create, Lifecycle.Read)
+  gateType: GateType;
+
+  @doc("The status of the Gate.")
+  @visibility(Lifecycle.Create, Lifecycle.Update, Lifecycle.Read)
+  status: GateState;
+}
+
+@doc("The type of staged rollout that the Gate is targeting.")
+@added(Versions.v2025_04_01_preview)
+union GateTargetType {
+  @doc("The Gate is controlling the staged rollout of an Update Run.")
+  updateRun: UpdateRunGateTargetType;
+}
+
+@doc("Whether the Gate is placed before or after the target.")
+@added(Versions.v2025_04_01_preview)
+union BeforeOrAfter {
+  string,
+
+  @doc("The Gate is before the target.")
+  Before: "Before",
+
+  @doc("The Gate is after the target.")
+  After: "After",
+}
+
+@doc("The Gate is targeting an Update Run staged rollout.")
+@added(Versions.v2025_04_01_preview)
+model UpdateRunGateTargetType {
+  @doc("The name of the Update Run.")
+  @visibility(Lifecycle.Read)
+  @pattern("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")
+  @minLength(1)
+  @maxLength(50)
+  name: string;
+
+  @doc("The Update Stage of the Update Run.")
+  @visibility(Lifecycle.Read)
+  @pattern("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")
+  @minLength(1)
+  @maxLength(50)
+  stage: string;
+
+  @doc("The Update Group of the Update Run.")
+  @visibility(Lifecycle.Read)
+  @pattern("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")
+  @minLength(1)
+  @maxLength(50)
+  group?: string;
+
+  @doc("Whether the Gate is placed before or after the update itself.")
+  @visibility(Lifecycle.Create, Lifecycle.Read)
+  beforeOrAfter: BeforeOrAfter;
+}
+
+scalar UpdateRunResourceId
+  extends Azure.Core.armResourceIdentifier<[
+    {
+      type: "Microsoft.ContainerService/fleets/updateRuns",
+    }
+  ]>;
+
+@doc("The resource id of staged rollout that the Gate is targeting.")
+@added(Versions.v2025_04_01_preview)
+union GateTargetId {
+  @doc("The Gate is controlling the staged rollout of an Update Run.")
+  updateRun: UpdateRunResourceId;
+}
+
+@doc("The target that the Gate is controlling, e.g. an Update Run.")
+@added(Versions.v2025_04_01_preview)
+model GateTarget {
+    @doc("The status of the Gate.")
+    @visibility(Lifecycle.Create, Lifecycle.Read)
+    id: GateTargetId;
+
+    @doc("The status of the Gate.")
+    @visibility(Lifecycle.Create, Lifecycle.Read)
+    type: GateTargetType;
+}
+
+@doc("The provisioning state of the Gate resource.")
+@lroStatus
+union GateProvisioningState {
+  string,
+  ResourceProvisioningState,
+}
+
+@armResourceOperations
+@added(Versions.v2025_04_01_preview)
+interface Gates {
+  get is ArmResourceRead<Gate>;
+
+  // The create and delete APIs are both internal-only as Gates are created by the Update Run during
+  // its processing. As such, we only expose the update API here.
+  #suppress "@azure-tools/typespec-azure-core/invalid-final-state" "must change at next release"
+  @Azure.Core.useFinalStateVia("azure-async-operation")
+  update is ArmResourcePatchAsync<
+    Gate,
+    GateProperties,
+    Azure.ResourceManager.Foundations.BaseParameters<Gate> &
+      IfMatchParameters<Gate> &
+      IfNoneMatchParameters<Gate>,
+  >;
+
+  listByFleet is ArmResourceListByParent<Gate>;
+}

specification/containerservice/Fleet.Management/main.tsp

@@ -2,6 +2,7 @@ import "@typespec/versioning";
 import "@azure-tools/typespec-azure-resource-manager";
 import "./fleet.tsp";
 import "./fleetmember.tsp";
+import "./gate.tsp";
 import "./update/common.tsp";
 import "./update/run.tsp";
 import "./update/strategy.tsp";

specification/containerservice/Fleet.Management/update/common.tsp

@@ -1,5 +1,7 @@
 import "@typespec/openapi";
+
 using TypeSpec.OpenAPI;
+using TypeSpec.Versioning;
 
 namespace Microsoft.ContainerService;
 
@@ -32,6 +34,16 @@ model UpdateStage {
 
   @doc("The time in seconds to wait at the end of this stage before starting the next one. Defaults to 0 seconds if unspecified.")
   afterStageWaitInSeconds?: int32;
+
+  @doc("A list of Gates that will be created before this Stage is updated.")
+  @added(Versions.v2025_04_01_preview)
+  @extension("x-ms-identifiers", ["displayName"])
+  beforeGates?: GateConfiguration[];
+
+  @doc("A list of Gates that will be created after this Stage is updated.")
+  @added(Versions.v2025_04_01_preview)
+  @extension("x-ms-identifiers", ["displayName"])
+  afterGates?: GateConfiguration[];
 }
 
 @doc("A group to be updated.")
@@ -44,4 +56,27 @@ model UpdateGroup {
   @minLength(1)
   @maxLength(50)
   name: string;
+
+  @doc("A list of Gates that will be created before this Group is updated.")
+  @added(Versions.v2025_04_01_preview)
+  @extension("x-ms-identifiers", ["displayName"])
+  beforeGates?: GateConfiguration[];
+
+  @doc("A list of Gates that will be created after this Group is updated.")
+  @added(Versions.v2025_04_01_preview)
+  @extension("x-ms-identifiers", ["displayName"])
+  afterGates?: GateConfiguration[];
+}
+
+@doc("GateConfiguration is used to define where Gates should be placed within the Update Run.")
+@added(Versions.v2025_04_01_preview)
+model GateConfiguration {
+  @doc("The human-readable display name of the Gate.")
+  @pattern("^[A-Za-z0-9].*$")
+  @minLength(1)
+  @maxLength(100)
+  displayName: string;
+
+  @doc("The type of the Gate determines how it is completed.")
+  type: GateType;
 }

specification/containerservice/Fleet.Management/update/run.tsp

@@ -50,6 +50,13 @@ scalar AutoUpgradeProfileId
     }
   ]>;
 
+scalar GateResourceId
+  extends Azure.Core.armResourceIdentifier<[
+    {
+      type: "Microsoft.ContainerService/fleets/gates",
+    }
+  ]>;
+
 @doc("The properties of the UpdateRun.")
 model UpdateRunProperties {
   @visibility("read")
@@ -254,6 +261,18 @@ model UpdateStageStatus {
   @doc("The list of groups to be updated as part of this UpdateStage.")
   groups?: UpdateGroupStatus[];
 
+  @visibility("read")
+  @extension("x-ms-identifiers", ["displayName"])
+  @doc("The list of Gates that will run before this UpdateStage.")
+  @added(Versions.v2025_04_01_preview)
+  beforeGates?: UpdateGateStatus[];
+
+  @visibility("read")
+  @extension("x-ms-identifiers", ["displayName"])
+  @doc("The list of Gates that will run after this UpdateStage.")
+  @added(Versions.v2025_04_01_preview)
+  afterGates?: UpdateGateStatus[];
+
   @visibility("read")
   @doc("The status of the wait period configured on the UpdateStage.")
   afterStageWaitStatus?: WaitStatus;
@@ -273,6 +292,18 @@ model UpdateGroupStatus {
   @extension("x-ms-identifiers", ["name"])
   @doc("The list of member this UpdateGroup updates.")
   members?: MemberUpdateStatus[];
+
+  @visibility("read")
+  @extension("x-ms-identifiers", ["displayName"])
+  @doc("The list of Gates that will run before this UpdateGroup.")
+  @added(Versions.v2025_04_01_preview)
+  beforeGates?: UpdateGateStatus[];
+
+  @visibility("read")
+  @extension("x-ms-identifiers", ["displayName"])
+  @doc("The list of Gates that will run after this UpdateGroup.")
+  @added(Versions.v2025_04_01_preview)
+  afterGates?: UpdateGateStatus[];
 }
 
 @doc("The status of the wait duration.")
@@ -286,6 +317,25 @@ model WaitStatus {
   waitDurationInSeconds?: int32;
 }
 
+@doc("The status of the Gate, as represented in the Update Run.")
+@added(Versions.v2025_04_01_preview)
+model UpdateGateStatus {
+  @doc("The human-readable display name of the Gate.")
+  @visibility("read")
+  @pattern("^[A-Za-z0-9].*$")
+  @minLength(1)
+  @maxLength(100)
+  displayName: string;
+
+  @doc("The status of the Gate.")
+  @visibility("read")
+  status?: UpdateStatus;
+
+  @doc("The resource id of the Gate.")
+  @visibility("read")
+  gateId?: GateResourceId;
+}
+
 @doc("The status of a member update operation.")
 model MemberUpdateStatus {
   @visibility("read")