cloudflare
Version:
The official TypeScript library for the Cloudflare API
671 lines • 25.8 kB
TypeScript
import { APIResource } from "../../../core/resource.js";
import { APIPromise } from "../../../core/api-promise.js";
import { RequestOptions } from "../../../internal/request-options.js";
export declare class BaseRollouts extends APIResource {
static readonly _key: readonly ['containers', 'applications', 'rollouts'];
/**
* 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>;
}
export declare 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 declare namespace RolloutCreateResponse {
/**
* User-specified container configuration changes.
*/
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;
}
namespace CurrentConfiguration {
/**
* User-provided SSH public key.
*/
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.
*/
interface EnvironmentVariable {
/**
* An environment variable name.
*/
name: string;
/**
* An environment variable value.
*/
value: string;
}
/**
* Settings for deployment observability such as logging.
*/
interface Observability {
/**
* Observability logging settings.
*/
logs?: Observability.Logs;
}
namespace Observability {
/**
* Observability logging settings.
*/
interface Logs {
enabled?: boolean;
}
}
}
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';
}
namespace Health {
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;
}
namespace Error {
/**
* An event within a Placement or a Job.
*/
interface Event {
id: string;
details: {
[]: 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: {
[]: unknown;
};
/**
* UTC timestamp string in ISO 8601 format.
*/
time: string;
type: 'Info' | 'Error' | 'Warn' | 'UserError' | 'SystemError';
}
}
/**
* Shows a count of application instance states.
*/
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.
*/
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;
}
namespace TargetConfiguration {
/**
* User-provided SSH public key.
*/
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.
*/
interface EnvironmentVariable {
/**
* An environment variable name.
*/
name: string;
/**
* An environment variable value.
*/
value: string;
}
/**
* Settings for deployment observability such as logging.
*/
interface Observability {
/**
* Observability logging settings.
*/
logs?: Observability.Logs;
}
namespace Observability {
/**
* Observability logging settings.
*/
interface Logs {
enabled?: boolean;
}
}
}
/**
* Progress details of an application rollout.
*/
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;
}
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.
*/
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.
*/
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;
}
namespace Step {
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.
*/
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 declare namespace RolloutCreateParams {
/**
* User-specified container configuration changes.
*/
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;
}
namespace TargetConfiguration {
/**
* User-provided SSH public key.
*/
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.
*/
interface EnvironmentVariable {
/**
* An environment variable name.
*/
name: string;
/**
* An environment variable value.
*/
value: string;
}
/**
* Settings for deployment observability such as logging.
*/
interface Observability {
/**
* Observability logging settings.
*/
logs?: Observability.Logs;
}
namespace Observability {
/**
* Observability logging settings.
*/
interface Logs {
enabled?: boolean;
}
}
}
/**
* Steps defining the rollout process.
*/
interface Step {
/**
* Description of the rollout step.
*/
description: string;
step_size: Step.StepSize;
}
namespace Step {
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, };
}
//# sourceMappingURL=rollouts.d.ts.map