cloudflare 7.2.0 → 7.3.0

package/src/resources/containers/applications/rollouts.ts

@@ -0,0 +1,807 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class BaseRollouts extends APIResource {
+  static override readonly _key: readonly ['containers', 'applications', 'rollouts'] = Object.freeze([
+    'containers',
+    'applications',
+    'rollouts',
+  ] as const);
+
+  /**
+   * Creates a rollout to update the application's configuration across instances
+   * with minimal downtime. Rollouts apply only to scheduler-backed applications with
+   * `scheduling_policy: "default"`. Versions and rollouts do not apply to
+   * applications with `scheduling_policy: "durable_object"`.
+   *
+   * @example
+   * ```ts
+   * const rollout =
+   *   await client.containers.applications.rollouts.create(
+   *     'application_id',
+   *     {
+   *       account_id: 'account-123',
+   *       description: 'description',
+   *       strategy: 'rolling',
+   *       target_configuration: {},
+   *     },
+   *   );
+   * ```
+   */
+  create(
+    applicationID: string,
+    params: RolloutCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<RolloutCreateResponse> {
+    const { account_id, ...body } = params;
+    return (
+      this._client.post(path`/accounts/${account_id}/containers/applications/${applicationID}/rollouts`, {
+        body,
+        ...options,
+      }) as APIPromise<{ result: RolloutCreateResponse }>
+    )._thenUnwrap((obj) => obj.result);
+  }
+}
+export class Rollouts extends BaseRollouts {}
+
+/**
+ * Represents the status and metadata of a rollout process for an application. For
+ * "rolling" strategy: includes steps and progress with instance counts. For
+ * "new_instances" strategy: the response omits steps and progress. Use percentage,
+ * version_distribution, and health.summary for status.
+ */
+export interface RolloutCreateResponse {
+  /**
+   * An identifier for a specific rollout within an application.
+   */
+  id: string;
+
+  /**
+   * UTC timestamp string in ISO 8601 format.
+   */
+  created_at: string;
+
+  /**
+   * User-specified container configuration changes.
+   */
+  current_configuration: RolloutCreateResponse.CurrentConfiguration;
+
+  /**
+   * Current application version before the rollout.
+   */
+  current_version: number;
+
+  description: string;
+
+  health: RolloutCreateResponse.Health;
+
+  /**
+   * Kind of the rollout process.
+   *
+   * - "full_auto": For rolling rollouts, starts progressing steps upon rollout
+   *   creation. For new_instances rollouts, advances percentage targets
+   *   automatically after target-version health is observed.
+   * - "full_manual": Requires manually progressing each step in the rollout using
+   *   the UpdateRollout's action paramater.
+   * - "durable_objects_auto": Default when the application is a DO application.
+   */
+  kind: 'full_auto' | 'full_manual' | 'durable_objects_auto';
+
+  /**
+   * Timestamp of the most recent update to status, health, or progress.
+   */
+  last_updated_at: string;
+
+  /**
+   * Current status of the rollout.
+   */
+  status: 'pending' | 'progressing' | 'completed' | 'reverted' | 'replaced';
+
+  /**
+   * The rollout strategy.
+   *
+   * - "rolling": Step-based rollout with health gates. Actively replaces instances
+   *   to reach each step's target percentage. Response includes steps and progress.
+   * - "new_instances": Percentage control over version distribution. Version sync
+   *   actively replaces instances to match the configured percentage. "full_auto"
+   *   ramps through fixed percentage targets after target-version health is
+   *   observed. Response includes percentage, version_distribution, and
+   *   health.summary.
+   */
+  strategy: 'rolling' | 'new_instances';
+
+  /**
+   * User-specified container configuration changes.
+   */
+  target_configuration: RolloutCreateResponse.TargetConfiguration;
+
+  /**
+   * Target application version after the rollout is complete and applied to all
+   * current instances.
+   */
+  target_version: number;
+
+  /**
+   * Current target version percentage (0-100). Only present for "new_instances"
+   * strategy.
+   */
+  percentage?: number;
+
+  /**
+   * Progress details of an application rollout.
+   */
+  progress?: RolloutCreateResponse.Progress;
+
+  /**
+   * Timestamp when the rollout started.
+   */
+  started_at?: string;
+
+  steps?: Array<RolloutCreateResponse.Step>;
+
+  /**
+   * Version percentage distribution. Only present for "new_instances" strategy. For
+   * "rolling" strategy, see progress.version_distribution instead.
+   */
+  version_distribution?: RolloutCreateResponse.VersionDistribution;
+}
+
+export namespace RolloutCreateResponse {
+  /**
+   * User-specified container configuration changes.
+   */
+  export interface CurrentConfiguration {
+    authorized_keys?: Array<CurrentConfiguration.AuthorizedKey>;
+
+    /**
+     * The command that runs when the container starts, passed to the entrypoint. You
+     * can override this at run-time. If you override only the command, it gets passed
+     * to the default entrypoint specified in the image.
+     */
+    command?: Array<string>;
+
+    /**
+     * The entry point for the container, specifying the executable to run when the
+     * container starts. You can override this at run-time. If you do, the default
+     * command from the image is ignored. Specify both entrypoint and command at
+     * run-time to completely replace the image defaults.
+     */
+    entrypoint?: Array<string>;
+
+    /**
+     * Container environment variables.
+     */
+    environment_variables?: Array<CurrentConfiguration.EnvironmentVariable>;
+
+    /**
+     * Image url.
+     */
+    image?: string;
+
+    /**
+     * The instance type configures vCPU, memory, and disk.
+     *
+     * - "lite": 1/16 vCPU, 256 MiB memory, 2 GB disk
+     * - "basic": 1/4 vCPU, 1 GiB memory, 4 GB disk
+     * - "standard-1": 1/2 vCPU, 4 GiB memory, 8 GB disk
+     * - "standard-2": 1 vCPU, 6 GiB memory, 12 GB disk
+     * - "standard-3": 2 vCPU, 8 GiB memory, 16 GB disk
+     * - "standard-4": 4 vCPU, 12 GiB memory, 20 GB disk
+     */
+    instance_type?: 'lite' | 'basic' | 'standard-1' | 'standard-2' | 'standard-3' | 'standard-4';
+
+    /**
+     * Settings for deployment observability such as logging.
+     */
+    observability?: CurrentConfiguration.Observability;
+  }
+
+  export namespace CurrentConfiguration {
+    /**
+     * User-provided SSH public key.
+     */
+    export interface AuthorizedKey {
+      /**
+       * An SSH public key.
+       */
+      public_key: string;
+
+      /**
+       * Optional human readable name for this key.
+       */
+      name?: string;
+    }
+
+    /**
+     * An environment variable with a value set.
+     */
+    export interface EnvironmentVariable {
+      /**
+       * An environment variable name.
+       */
+      name: string;
+
+      /**
+       * An environment variable value.
+       */
+      value: string;
+    }
+
+    /**
+     * Settings for deployment observability such as logging.
+     */
+    export interface Observability {
+      /**
+       * Observability logging settings.
+       */
+      logs?: Observability.Logs;
+    }
+
+    export namespace Observability {
+      /**
+       * Observability logging settings.
+       */
+      export interface Logs {
+        enabled?: boolean;
+      }
+    }
+  }
+
+  export interface Health {
+    errors: Array<Health.Error>;
+
+    /**
+     * Shows a count of application instance states.
+     */
+    instances: Health.Instances;
+
+    /**
+     * High-level health assessment. Only populated for "new_instances" strategy. Based
+     * on a sample of target-version instances rather than a full count.
+     *
+     * - "pending": Zero target-version instances exist yet.
+     * - "healthy": Every sampled target-version instance reports running or active.
+     * - "degraded": Some sampled instances remain starting or scheduling.
+     * - "unhealthy": One or more sampled instances have failed.
+     */
+    summary?: 'healthy' | 'degraded' | 'unhealthy' | 'pending';
+  }
+
+  export namespace Health {
+    export interface Error {
+      /**
+       * An event within a Placement or a Job.
+       */
+      event: Error.Event;
+
+      /**
+       * An instance ID represents an identifier of an instance configuration that
+       * maintains an underlying placement.
+       */
+      instance_id: string;
+    }
+
+    export namespace Error {
+      /**
+       * An event within a Placement or a Job.
+       */
+      export interface Event {
+        id: string;
+
+        details: { [key: string]: unknown };
+
+        message: string;
+
+        /**
+         * Name of the event that describes the kind event that happened.
+         *
+         * - SchedulerPlaced: It's the first event that creates a container placement. It
+         *   happens when the Containers runtime was able to retrieve deployment resources
+         *   and start verifying everything is correct.
+         * - NetworkingIPAssigned: It's sent when the Containers runtime maps the IP to the
+         *   container.
+         * - VMStarted: It's sent when the Containers runtime starts the VM. The container
+         *   might remain unhealthy at this point.
+         * - ImagePulled: It's sent when the Containers runtime pulls the image
+         *   successfully.
+         * - ImagePullError: It's sent when the Containers runtime is having issues pulling
+         *   the image. The message and details have more information on what happened for
+         *   debugging.
+         * - VMFailedToStart: It's sent when the Containers runtime was unable to boot the
+         *   VM.
+         * - VMStopping: It's sent when the scheduler is stopping the VM.
+         * - VMStopped: It's sent when the VM finally exits.
+         * - VMFailed: It's sent when the scheduling of the VM failed in the current
+         *   location.
+         * - RuntimeStartFailed: It's sent when the runtime hits an internal error.
+         * - SSHStarted: It's sent when the container gains network connectivity and opens
+         *   the SSH port. Containers only send this event when SSH keys exist.
+         * - CheckUpdate: Sent when the status of a health or readiness check changes. This
+         *   may also affect the health status of the placement.
+         * - DurableObjectConnected: Sent when a durable object instance connects and gains
+         *   control of the deployment. This event is only sent for durable object
+         *   deployments. It is sent after VMStarted.
+         * - ContainerStarted: It's sent when the container starts running.
+         */
+        name:
+          | 'SchedulerPlaced'
+          | 'NetworkingIPAssigned'
+          | 'VMStarted'
+          | 'ImagePulled'
+          | 'ImagePullError'
+          | 'VMFailedToStart'
+          | 'NetworkingIPAssignmentFailed'
+          | 'VMRunning'
+          | 'VMStopping'
+          | 'VMStopped'
+          | 'VMFailed'
+          | 'RuntimeStartFailed'
+          | 'SSHStarted'
+          | 'ServiceHealthUpdates'
+          | 'CheckUpdate'
+          | 'DurableObjectConnected'
+          | 'ContainerStarted';
+
+        statusChange: { [key: string]: unknown };
+
+        /**
+         * UTC timestamp string in ISO 8601 format.
+         */
+        time: string;
+
+        type: 'Info' | 'Error' | 'Warn' | 'UserError' | 'SystemError';
+      }
+    }
+
+    /**
+     * Shows a count of application instance states.
+     */
+    export interface Instances {
+      /**
+       * Number of instances whose runtime reports the container as running
+       * (container_status = "running"). This is a subset of the placements that remain
+       * up: an instance that is already bound to a Durable Object and serving traffic is
+       * counted under "assigned" until its container_status catches up to "running", so
+       * container_status can briefly lag Durable Object attachment under churn. To
+       * estimate running, Durable-Object-bound instances, sum "active" + "assigned"
+       * rather than reading "active" alone.
+       */
+      active: number;
+
+      /**
+       * Number of instances bound to a Durable Object with a running placement whose
+       * container_status remains behind "running". These count as live, serving
+       * instances; "active" + "assigned" approximates the running, Durable-Object-bound
+       * count.
+       */
+      assigned: number;
+    }
+  }
+
+  /**
+   * User-specified container configuration changes.
+   */
+  export interface TargetConfiguration {
+    authorized_keys?: Array<TargetConfiguration.AuthorizedKey>;
+
+    /**
+     * The command that runs when the container starts, passed to the entrypoint. You
+     * can override this at run-time. If you override only the command, it gets passed
+     * to the default entrypoint specified in the image.
+     */
+    command?: Array<string>;
+
+    /**
+     * The entry point for the container, specifying the executable to run when the
+     * container starts. You can override this at run-time. If you do, the default
+     * command from the image is ignored. Specify both entrypoint and command at
+     * run-time to completely replace the image defaults.
+     */
+    entrypoint?: Array<string>;
+
+    /**
+     * Container environment variables.
+     */
+    environment_variables?: Array<TargetConfiguration.EnvironmentVariable>;
+
+    /**
+     * Image url.
+     */
+    image?: string;
+
+    /**
+     * The instance type configures vCPU, memory, and disk.
+     *
+     * - "lite": 1/16 vCPU, 256 MiB memory, 2 GB disk
+     * - "basic": 1/4 vCPU, 1 GiB memory, 4 GB disk
+     * - "standard-1": 1/2 vCPU, 4 GiB memory, 8 GB disk
+     * - "standard-2": 1 vCPU, 6 GiB memory, 12 GB disk
+     * - "standard-3": 2 vCPU, 8 GiB memory, 16 GB disk
+     * - "standard-4": 4 vCPU, 12 GiB memory, 20 GB disk
+     */
+    instance_type?: 'lite' | 'basic' | 'standard-1' | 'standard-2' | 'standard-3' | 'standard-4';
+
+    /**
+     * Settings for deployment observability such as logging.
+     */
+    observability?: TargetConfiguration.Observability;
+  }
+
+  export namespace TargetConfiguration {
+    /**
+     * User-provided SSH public key.
+     */
+    export interface AuthorizedKey {
+      /**
+       * An SSH public key.
+       */
+      public_key: string;
+
+      /**
+       * Optional human readable name for this key.
+       */
+      name?: string;
+    }
+
+    /**
+     * An environment variable with a value set.
+     */
+    export interface EnvironmentVariable {
+      /**
+       * An environment variable name.
+       */
+      name: string;
+
+      /**
+       * An environment variable value.
+       */
+      value: string;
+    }
+
+    /**
+     * Settings for deployment observability such as logging.
+     */
+    export interface Observability {
+      /**
+       * Observability logging settings.
+       */
+      logs?: Observability.Logs;
+    }
+
+    export namespace Observability {
+      /**
+       * Observability logging settings.
+       */
+      export interface Logs {
+        enabled?: boolean;
+      }
+    }
+  }
+
+  /**
+   * Progress details of an application rollout.
+   */
+  export interface Progress {
+    /**
+     * Current step being executed in the rollout process. Initialized to 0.
+     */
+    current_step: number;
+
+    /**
+     * Total number of instances the rollout affects.
+     */
+    total_instances: number;
+
+    /**
+     * Total number of steps in the rollout.
+     */
+    total_steps: number;
+
+    /**
+     * Number of instances updated in the rollout process.
+     */
+    updated_instances: number;
+
+    /**
+     * Expected distribution of instances per version, based on the current percentage
+     * split. Populated during active rollouts. Values derive from the version
+     * percentage weights rather than actual running instance counts.
+     */
+    version_distribution?: Progress.VersionDistribution;
+  }
+
+  export namespace Progress {
+    /**
+     * Expected distribution of instances per version, based on the current percentage
+     * split. Populated during active rollouts. Values derive from the version
+     * percentage weights rather than actual running instance counts.
+     */
+    export interface VersionDistribution {
+      /**
+       * Expected number of instances remaining on the current (old) version based on the
+       * current percentage split. Only populated for "rolling" strategy.
+       */
+      current_version_instances?: number;
+
+      /**
+       * The percentage of new instances being scheduled on the current version (100 -
+       * target_version_percentage). Only populated for "new_instances" strategy.
+       */
+      current_version_percentage?: number;
+
+      /**
+       * Expected number of instances scheduled for the target (new) version based on the
+       * current percentage split. Only populated for "rolling" strategy.
+       */
+      target_version_instances?: number;
+
+      /**
+       * The active percentage of new instances being scheduled on the target version.
+       * For "rolling", this reflects the step_size.percentage of the current active
+       * step. For "new_instances", this reflects the user-set percentage.
+       */
+      target_version_percentage?: number;
+    }
+  }
+
+  /**
+   * Steps within the rollout process.
+   */
+  export interface Step {
+    /**
+     * The sequential order of the rollout step, automatically assigned starting from
+     * 1, based on the total number of steps in the rollout process.
+     */
+    id: number;
+
+    /**
+     * Description of the rollout step.
+     */
+    description: string;
+
+    /**
+     * Status of the rollout step.
+     */
+    status: 'pending' | 'progressing' | 'reverting' | 'completed' | 'reverted';
+
+    step_size: Step.StepSize;
+
+    /**
+     * UTC timestamp string in ISO 8601 format.
+     */
+    completed_at?: string;
+
+    /**
+     * Reason for the step's current status.
+     */
+    reason?: string;
+
+    /**
+     * UTC timestamp string in ISO 8601 format.
+     */
+    started_at?: string;
+  }
+
+  export namespace Step {
+    export interface StepSize {
+      /**
+       * Percentage of instances affected in this step. Min 10% and Max 100%.
+       */
+      percentage: number;
+    }
+  }
+
+  /**
+   * Version percentage distribution. Only present for "new_instances" strategy. For
+   * "rolling" strategy, see progress.version_distribution instead.
+   */
+  export interface VersionDistribution {
+    /**
+     * Percentage of instances on the current (old) version.
+     */
+    current_version_percentage: number;
+
+    /**
+     * Percentage of instances on the target (new) version.
+     */
+    target_version_percentage: number;
+  }
+}
+
+export interface RolloutCreateParams {
+  /**
+   * Path param: Account identifier.
+   */
+  account_id: string;
+
+  /**
+   * Body param: Description of the rollout process.
+   */
+  description: string;
+
+  /**
+   * Body param: Strategy used for the rollout.
+   *
+   * - "rolling": Step-based rollout with health gates. Actively replaces instances
+   *   to reach each step's target percentage.
+   * - "new_instances": Percentage control over version distribution. Version sync
+   *   actively replaces instances to match the configured percentage. The
+   *   "full_auto" kind advances through fixed percentage targets after
+   *   target-version health is observed.
+   */
+  strategy: 'rolling' | 'new_instances';
+
+  /**
+   * Body param: User-specified container configuration changes.
+   */
+  target_configuration: RolloutCreateParams.TargetConfiguration;
+
+  /**
+   * Body param: Kind of the rollout process. Defaults to "full_auto".
+   *
+   * - "full_auto": For rolling rollouts, starts progressing steps upon rollout
+   *   creation. For new_instances rollouts, advances percentage targets
+   *   automatically after target-version health is observed.
+   * - "full_manual": Requires manually progressing each step in the rollout using
+   *   the UpdateRollout's action parameter.
+   */
+  kind?: 'full_auto' | 'full_manual';
+
+  /**
+   * Body param: Initial target version percentage (0-100). Version sync actively
+   * replaces instances to match. Required when strategy is "new_instances" and kind
+   * is "full_manual". When strategy is "new_instances" and kind is "full_auto",
+   * omitted percentage starts at 10% or the smallest percentage that targets at
+   * least one instance. Unused for "rolling".
+   */
+  percentage?: number;
+
+  /**
+   * Body param: Percentage of rollout to increase in each step when "steps" is
+   * absent. Applicable values: 5, 10, 20, 25, 50, 100. These create rollouts with
+   * 20, 10, 5, 4, 2, 1 steps respectively. Only valid for "rolling" strategy.
+   */
+  step_percentage?: 5 | 10 | 20 | 25 | 50 | 100;
+
+  /**
+   * Body param: Steps defining the rollout process, used when "step_percentage" is
+   * absent. Specify only one of "step_percentage" or "steps" when creating a
+   * rollout. "steps" allow granular control over each step. Only valid for "rolling"
+   * strategy.
+   */
+  steps?: Array<RolloutCreateParams.Step>;
+}
+
+export namespace RolloutCreateParams {
+  /**
+   * User-specified container configuration changes.
+   */
+  export interface TargetConfiguration {
+    authorized_keys?: Array<TargetConfiguration.AuthorizedKey>;
+
+    /**
+     * The command that runs when the container starts, passed to the entrypoint. You
+     * can override this at run-time. If you override only the command, it gets passed
+     * to the default entrypoint specified in the image.
+     */
+    command?: Array<string>;
+
+    /**
+     * The entry point for the container, specifying the executable to run when the
+     * container starts. You can override this at run-time. If you do, the default
+     * command from the image is ignored. Specify both entrypoint and command at
+     * run-time to completely replace the image defaults.
+     */
+    entrypoint?: Array<string>;
+
+    /**
+     * Container environment variables.
+     */
+    environment_variables?: Array<TargetConfiguration.EnvironmentVariable>;
+
+    /**
+     * Image url.
+     */
+    image?: string;
+
+    /**
+     * The instance type configures vCPU, memory, and disk.
+     *
+     * - "lite": 1/16 vCPU, 256 MiB memory, 2 GB disk
+     * - "basic": 1/4 vCPU, 1 GiB memory, 4 GB disk
+     * - "standard-1": 1/2 vCPU, 4 GiB memory, 8 GB disk
+     * - "standard-2": 1 vCPU, 6 GiB memory, 12 GB disk
+     * - "standard-3": 2 vCPU, 8 GiB memory, 16 GB disk
+     * - "standard-4": 4 vCPU, 12 GiB memory, 20 GB disk
+     */
+    instance_type?: 'lite' | 'basic' | 'standard-1' | 'standard-2' | 'standard-3' | 'standard-4';
+
+    /**
+     * Settings for deployment observability such as logging.
+     */
+    observability?: TargetConfiguration.Observability;
+  }
+
+  export namespace TargetConfiguration {
+    /**
+     * User-provided SSH public key.
+     */
+    export interface AuthorizedKey {
+      /**
+       * An SSH public key.
+       */
+      public_key: string;
+
+      /**
+       * Optional human readable name for this key.
+       */
+      name?: string;
+    }
+
+    /**
+     * An environment variable with a value set.
+     */
+    export interface EnvironmentVariable {
+      /**
+       * An environment variable name.
+       */
+      name: string;
+
+      /**
+       * An environment variable value.
+       */
+      value: string;
+    }
+
+    /**
+     * Settings for deployment observability such as logging.
+     */
+    export interface Observability {
+      /**
+       * Observability logging settings.
+       */
+      logs?: Observability.Logs;
+    }
+
+    export namespace Observability {
+      /**
+       * Observability logging settings.
+       */
+      export interface Logs {
+        enabled?: boolean;
+      }
+    }
+  }
+
+  /**
+   * Steps defining the rollout process.
+   */
+  export interface Step {
+    /**
+     * Description of the rollout step.
+     */
+    description: string;
+
+    step_size: Step.StepSize;
+  }
+
+  export namespace Step {
+    export interface StepSize {
+      /**
+       * Percentage of instances affected in this step. Min 10% and Max 100%.
+       */
+      percentage: number;
+    }
+  }
+}
+
+export declare namespace Rollouts {
+  export {
+    type RolloutCreateResponse as RolloutCreateResponse,
+    type RolloutCreateParams as RolloutCreateParams,
+  };
+}